Sections

API Methods

Result objects

Ravelry API Documentation

Last updated 2026-03-30

heart Welcome!

Once you decide which type of credentials you need, create your App and keys by visiting https://www.ravelry.com/pro/developer. If you do not already have a free Pro account you’ll be prompted to create one.

This documentation lists the API methods, inputs, and outputs but it doesn't describe how to put it all together. You may find the Ravelry API group to be helpful.

You are also very welcome to email us at api@ravelry.com. Most API improvements originate from requests from users.

Accessing Ravelry with HTTP Basic Auth: read only access

If you only need to use read-only API methods, read-only Basic Auth is the simplest way to get started.

When you use your read-only credentials, you will only be able to call API methods that are not marked as "authenticated" in the documentation.

Use HTTP Basic Authentication with your HTTP client and supply the username and password taken from your app's credentials. SSL is required.

Example:

curl -u basic_auth_username:basic_auth_password https://api.ravelry.com/current_user.json

Authenticating via HTTP Basic Auth: personal account access

If you only need to sign in to Ravelry as yourself, you can use this simple method to access the API. You do not have to request specific permissions when authenticating this way - all permissions are granted.

Use HTTP Basic Authentication with your HTTP client and supply your access key as the username and your personal key (not your secret key) as the password. Note that SSL is required: you will receive a 403 error if you do not use HTTPS.

IMPORTANT: "Basic Auth: personal account access" credentials provide full access to the Ravelry account that they are associated with. This is intended for personal projects.

A quick example:

curl -u basic_auth_username:basic_auth_personal_key https://api.ravelry.com/current_user.json

Authenticating with Ravelry via OAuth 2.0

Use your client ID and client secret to authenticate with Ravelry using any OAuth 2 library.

The OAuth 2 URLs are:

See "OAuth scope" below for information on requesting specific permissions.

When requesting your token, we support basic auth (the "Authorization" header) for passing your client ID and secret. Submitting these as form parameters (also called "body auth") is not supported.

OAuth 2 tokens expire in 24 hours. You will probably want to request the "offline" scope so that you can receive a refresh token. Your OAuth client library should allow you to refresh your access token before it expires so that you do not have to re-authorize. Your application should handle HTTP 401 Unauthorized responses by re-authenticating the user.

Authenticating with Ravelry via OAuth 1.0a

Use your consumer key and consumer secret authenticate with Ravelry using any OAuth 1.0a library.

The OAuth URLs are:

See "OAuth scope" below for information on requesting specific permissions.

OAuth tokens are long-lived but they can expire after a period of inactivity or if the user revokes access. Your application should handle HTTP 401 Unauthorized responses by re-authenticating the user.

OAuth scopes (permissions)

The OAuth request_token and OAuth 2 token methods accept an optional "scope" parameter. Use this parameter when your application needs to request additional privileges that aren't granted by default. To request several privileges, separate the values with a space.

If you are using a personal key instead of OAuth, you do not need to request specific permissions.

Key Description
offline standard OAuth 2.0 scope for requesting refresh tokens
forum-write create, edit, and delete forum posts
message-write create (ie. send messages to other users) and delete private messages
patternstore-read enumerate the pattern stores that the user administers as well as the products within those stores
patternstore-pdf (currently limited access, available by request) generate download links for PDF files within the user's pattern stores
deliveries-read list the products that have been purchased by or gifted to the current user
library-pdf directly download PDFs from a user's library using generate_download_link. note: tokens that request this scope will expire more quickly than usual and may also expire if a rate limit is exceeded. You may want to hold both a normal token and a library-pdf token for each user when this permission is requested.

There are also scopes which allow you to select a minimal set of privileges.

Key Description
profile-only allows access to /current_user.json and nothing else
carts-only callows access to /carts/*.json and nothing else

HTTP Status Codes

Your application may encounter the following client errors (4xx) and server errors (5xx)

Input Objects

Some API calls show a parameter named "data" with a TypeName#POST object as the parameter data type.

For these methods, you may submit either a JSON object or name/value pairs. To submit JSON, you may POST it normally with the parameter name "data" (recommended) or submit it as the raw POST data. Note that you must submit JSON instead of name/value pairs if you want to include nested data.

Examples with the usual form encoding left out:

JSON as the raw post:
POST {name: "Bond", nickname: "007"}

JSON with a key/value:
POST data={name: "Bond", nickname: "007"}

Plain parameters: if you don't need to or want to nest data. Note that each parameter is submitted individually and not nested under "data"
POST name=foo&nickname=007

Sorting and Pagination

Unless otherwise specified, all API calls that accept a "sort" sort order parameter have 2 special features:

Methods that paginate accept "page_size" and "page" parameters and return a result object that contains a Paginator. A paginator object includes the following properties: page_count, page, page_size, results, last_page

Additional documentation

API Methods

/

/color_families

GET /color_families.json
Retrieve list of color families

Return Values

Name Type Required Description
color_families Array, ColorFamily Yes All color families

Example

/color_families.json

/current_user authenticated

GET /current_user.json
Get current user

Return Values

Name Type Required Description
user User (full) Yes User

Example

/current_user.json

/fiber_attributes

GET /fiber_attributes.json
Retrieve list of the current fiber attributes

Return Values

Name Type Required Description
fiber_attributes Array, FiberAttribute Yes All fiber attributes

Notes

Fiber attributes seldom change, I'd recommend caching them for up to 24 hours. This method does not require an API key.

Example

/fiber_attributes.json

/fiber_categories

GET /fiber_categories.json
List the current fiber categories

Return Values

Name Type Required Description
fiber_categories Array, FiberCategory (list) Yes List of all fiber categories

Notes

Fiber categories seldom change, I'd recommend caching them for up to 24 hours. This method does not require an API key.
GET /search.json
Global search

Parameters

Name Type Required Description
query String Yes Search term for fulltext searching yarns
limit Integer Number of results to retrieve. Default = 50, maximum = 500
types String Optional space delimited list of result types to include. Available options: User, PatternAuthor, PatternSource, Pattern, YarnCompany, Yarn, Group, Event, Project, Page, Topic, Shop

Return Values

Name Type Required Description
results Array, Object Yes Search results, see below for details about the contents of the result object

Notes

Global search is a simple text-only search that returns basic information about each search result. ***For more powerful search APIs***, see /patterns/search.json, /yarns/search.json, etc.


Result object contents
Key Description
title Title of the object
type_name Type of object, suitable for displaying to end users
caption (optional) Caption/description related to object, suitable for displaying to end users
tiny_image_url (optional) Image suitable for displaying inline with text. Typically 24x24.
image_url (optional) Primary image associated with the object. Typically 500px on the longest side.
record Nested object with information about the matching record
Key Description
type Type of record, corresponds with API Result Types
id id of record
permalink current permalink for record
uri API URI for retrieving information about the record

/yarn_weights

GET /yarn_weights.json
Retrieve list of active yarn weights

Return Values

Name Type Required Description
yarn_weights Array, YarnWeight Yes All active yarn weights

Example

/yarn_weights.json

app

app/config/delete authenticated

POST /app/config/delete.json
Delete a Ravelry-specific application configuration setting

Parameters

Name Type Required Description
keys String Yes Space delimited list of keys to delete

Return Values

Name Type Required Description
config Hash Yes Previous contents of keys that were deleted

Example

/app/config/delete.json?keys=foo+bar

app/config/get authenticated

GET /app/config/get.json
Get Ravelry-specific application configuration

Parameters

Name Type Required Description
keys String Space delimited list of keys to retrieve

Return Values

Name Type Required Description
config Hash Yes Contents of keys that were updated

Example

/app/config/set.json?keys=foo+bar

app/config/set authenticated

POST /app/config/set.json
Set Ravelry-specific application configuration

Parameters

Name Type Required Description
(key_names) String Yes Key/value pairs to set

Return Values

Name Type Required Description
config Hash Yes Contents of keys that were updated

Notes

Send each key/value that you want to set as query parameters. Currently supported parameters are:
  • "profile_badge" [0|1] enable application badge in user's profile. This should be an *opt-in* setting in your app.

Example

/app/config/set.json?profile_badge=1

app/data/delete authenticated

POST /app/data/delete.json
Delete a user and application specific piece of data (key/value)

Parameters

Name Type Required Description
keys String Yes Space delimited list of keys to delete

Return Values

Name Type Required Description
data Hash Yes Previous contents of keys that were deleted

Example

/app/data/delete.json?keys=foo+bar

app/data/get authenticated

GET /app/data/get.json
Get user and application specific data

Parameters

Name Type Required Description
keys String Space delimited list of keys to retrieve

Return Values

Name Type Required Description
data Hash Yes Contents of keys that were updated

Notes

You are welcome to use Ravelry's key/value storage to store any application specific data. This could be used to offer syncing, backup of settings or data, etc. to your users.

Example

/app/data/get.json?keys=foo

app/data/set authenticated

POST /app/data/set.json
Store user and application-specific data.

Parameters

Name Type Required Description
(key_names) String Yes Key/value pairs to set

Return Values

Name Type Required Description
data Hash Yes Contents of keys that were updated

Notes

You are welcome to use Ravelry's key/value storage to store any application specific data. This could be used to offer syncing, backup of settings or data, etc. to your users. Send each key/value that you want to set as query parameters.

Example

/app/data/set.json?foo=bar

bundled_items

bundled_items/delete authenticated

DELETE /bundled_items/{bundled_item_id}.json
Delete bundled item

URI Parameters

Name Type Required Description
bundled_item_id Integer Yes Bundled item to delete

Return Values

Name Type Required Description
item BundledItem (full) Yes Bundled item that was deleted

bundled_items/show authenticated

GET /bundled_items/{bundled_item_id}.json
Get single bundled_item

URI Parameters

Name Type Required Description
bundled_item_id Integer Yes Bundled item to retrieve

Return Values

Name Type Required Description
bundled_item BundledItem (full) Yes Bundled item
item Object Yes Item

bundles

bundles/create authenticated

POST /people/{username}/bundles/create.json
Create bundle record

URI Parameters

Name Type Required Description
username String Yes User to create bundle for

Parameters

Name Type Required Description
data Bundle (POST) Yes Bundle JSON object

Return Values

Name Type Required Description
bundle Bundle (full) Yes Bundle

Example

/people/username/bundles/create.json { "name": "my awesome bundle", "notes": "stuff that is awesome." }

bundles/delete authenticated

DELETE /people/{username}/bundles/{id}.json
Delete a bundle record

URI Parameters

Name Type Required Description
username String Yes User to retrieve bundle from
id Integer Yes Id of the bundle record that should be deleted

Return Values

Name Type Required Description
bundle Bundle (full) Yes The deleted record

bundles/list authenticated

GET /people/{username}/bundles/list.json
Get bundles list

URI Parameters

Name Type Required Description
username String Yes User to retrieve bundles from

Parameters

Name Type Required Description
owner_types Array, String Space delimited list of types of bundles to retrieve. Accepted options: designer, group, personal. Defaults to all types.
query String Search query for bundles.
page Integer Result page to retrieve. Defaults to 1 (the first page).
page_size Integer Defaults to 25. Maximum size accepted = 100

Return Values

Name Type Required Description
bundles Array, Bundle (list) Yes Matching bundles
paginator Paginator Yes Pagination object with total results, pages

Notes

Bundles are returned in ordered by creation date, descending. If you request a mix of different types of bundles, you can use the "type" key to determine the type of bundle that you are receiving.

Example

/people/username/bundles/list.json

bundles/show authenticated

GET /people/{username}/bundles/{id}.json
Get bundle record

URI Parameters

Name Type Required Description
username String Yes User to retrieve bundle from
id Integer Yes Bundle to retrieve

Return Values

Name Type Required Description
bundle Bundle (full) Yes Bundle

Example

/people/username/bundles/989.json

bundles/update authenticated

POST /people/{username}/bundles/{id}.json
Update an existing bundle record

URI Parameters

Name Type Required Description
username String Yes User who owns the bundle
id Integer Yes ID of the bundle to update

Parameters

Name Type Required Description
data Bundle (POST) Yes Bundle JSON object

Return Values

Name Type Required Description
bundle Bundle (full) Yes Bundle

Example

/people/username/bundle/989.json { "name": "an updated name" }

carts

carts/add authenticated

POST /carts/{id}/add.json
Add a product to a cart. Used to integrate external pattern stores with the Ravelry library.

URI Parameters

Name Type Required Description
id Integer Yes ID of the cart to update

Parameters

Name Type Required Description
item_code String Yes SKU of the product to add. Configurable in your Ravelry store as alphanumeric "Item number".

Return Values

Name Type Required Description
cart Cart (full) Yes The cart and its current contents

carts/create authenticated

POST /carts/create.json
Create a new cart. Used to integrate external pattern stores with the Ravelry library.

Parameters

Name Type Required Description
store_id Integer Yes ID of store to associate with the cart. Contact Ravelry for your cart access and your store ID.

Return Values

Name Type Required Description
cart Cart (full) Yes The newly created cart

Notes

You can access Cart API methods after asking Ravelry to enable this option for your app. You will then be able to create and checkout carts in stores that are associated with the Pro Account that your app is associated with.

carts/external_checkout authenticated

POST /carts/{id}/external_checkout.json
Notify Ravelry that a cart has been checked out (paid for) externally. This will create an invoice, mark it as paid, and deliver the products to the customer.

URI Parameters

Name Type Required Description
id Integer Yes ID of the cart to checkout

Parameters

Name Type Required Description
payment_reference String Custom text to associate with the Ravelry invoice/receipt. Not visible to customer. Normally, you'd use your internal invoice number

Return Values

Name Type Required Description
invoice Invoice (cart) Yes The generated invoice. You may want to store the ID for future reference.

Notes

You can access Cart API methods after asking Ravelry to enable this option for your app. You will then be able to create and checkout carts in stores that are associated with the Pro Account that your app is associated with. If you are only using the Ravelry API for external checkouts (adding patterns to a user's Ravelry library), we recommend using the carts-only OAuth scope so that the user does not have to provide unnecessary access to their Ravelry account. See Oauth Permissions.

carts/loveknitting/external_checkout authenticated

POST /carts/loveknitting/{id}/external_checkout.json
Notify Ravelry that a cart has been checked out (paid for) at loveknitting.

URI Parameters

Name Type Required Description
id Integer Yes ID of the cart to checkout

Parameters

Name Type Required Description
payment_reference String Custom text to associate with the Ravelry invoice/receipt. Not visible to customer. Normally, you'd use your internal invoice number
product_id_list String Space delimited list of product IDs that were purchased.

Return Values

Name Type Required Description
invoice Invoice (cart) Yes The generated invoice. You may want to store the ID for future reference.

comments

comments/create

POST /comments/create.json
Post a comment related to an object

Parameters

Name Type Required Description
type String Yes The type of item that is being commented on. One of: project, pattern, yarn, stash.
commented_id Integer Yes ID of item being commented on.
body String Yes Comment body. Text, Markdown, HTML or some combination of those is accepted.
reply_to_id Integer ID of comment being replied to. Only the owner of a project, stash, yarn or pattern can post replies.

Return Values

Name Type Required Description
comment Comment (full) Yes The newly created comment

Required permissions

message-write

Notes

Creates and immediately posts a comment. Comments cannot be edited after they are created but they can be deleted. Note that the returned comment body may differ from the submitted text because Markdown will be processed and unacceptable HTML tags will be removed. This method requires message-write permission

comments/delete

DELETE /comments/{id}.json
Delete a comment

URI Parameters

Name Type Required Description
id Integer ID of the comment being deleted.

Return Values

Name Type Required Description
comment Comment (full) Yes The deleted comment

Required permissions

message-write

Notes

A user may delete their own comments as well as any comments posted on items that they own. This method requires message-write permission

comments/list

GET /people/{username}/comments/list.json
Get list of comments left by a user

URI Parameters

Name Type Required Description
username String Yes User to retrieve projects from

Parameters

Name Type Required Description
page Integer Result page to retrieve. Defaults to 1 (the first page).
page_size Integer Defaults to 25. Maximum size accepted = 100

Return Values

Name Type Required Description
comments Array, Comment (history) Yes

Notes

The comment histories of other Ravelry users cannot be retrieved.

deliveries

deliveries/list

GET /deliveries/list.json
List the products that have been purchased by or gifted to the current user

Parameters

Name Type Required Description
page Integer Result page to retrieve. Defaults to 1 (the first page).
page_size Integer Defaults to 25. Maximum size accepted = 100

Return Values

Name Type Required Description
deliveries Array, Delivery (list) Yes Results
paginator Paginator Yes Pagination object with total results, pages

Required permissions

deliveries-read

Notes

A delivery will contain one more more products. Each product may be associated with some number of patterns or pattern sources. Deliveries are returned in ordered by creation date, descending. This method requires deliveries-read permission

Example

/deliveries/list.json

deliveries/renew

POST /deliveries/#{id}/renew.json
Renew an expired digital product delivery token/url.

URI Parameters

Name Type Required Description
id Integer Yes Delivery ID

Parameters

Name Type Required Description
customer_email_address String Yes The email address supplied during the initial checkout

Return Values

Name Type Required Description
delivery Delivery (receipt) Yes the renewed delivery

Notes

Renews an expired delivery link/token so that the delivery_url in the returned object is useable by an end user. Note that this API method is only useful to retail shops who are participating in the In Store Sales program.

designers

designers/show authenticated

GET /designers/{id}.json
Get designer details

URI Parameters

Name Type Required Description
id Integer Yes Designer ID or permalink

Parameters

Name Type Required Description
include Array, String Extra result parts to include. Space delimited. Accepted options: featured_bundles

Return Values

Name Type Required Description
pattern_author PatternAuthor (full) Yes Designer (pattern author) profile
featured_bundles Array, Bundle (list) Featured bundles, if requested

Notes

To search/sort a designer's patterns, use the pattern search API and set the "designer-link" parameter to the designer permalink (preferred) or set the "designs-by" parameter to the designer's name.

About profile notes: on Ravelry.com, the user blurb (pattern_author.users[0].blurb) is displayed if the designer does not have any profile notes.

Example

/designers/1.json?include=featured_bundles

drafts

drafts/create

POST /drafts/patterns/create.json
Create a draft pattern

Parameters

Name Type Required Description
data DraftPattern (POST) Yes Draft pattern data

Return Values

Name Type Required Description
draft_pattern DraftPattern (full) Yes Draft pattern

Required permissions

patternstore-read OR patternstore-write

Notes

Note: You must supply a draft_business_id. The draft pattern will be associated with this business (pro account) One way to see available businesses is by using the /patterns/drafts/list.json API call

drafts/create_photo authenticated

POST /drafts/patterns/{draft_pattern_id}/create_photo.json
Add a photo to a draft pattern (using an uploaded image or URL as a source)

URI Parameters

Name Type Required Description
draft_pattern_id String Yes Draft pattern id

Parameters

Name Type Required Description
image_id Integer Uploaded image to use, created via /upload/image.json
source_url String URL of the image to use (preferably high-res and 1600px on the smallest side minimum)

Return Values

Name Type Required Description
status_token String Yes Token that can be used to check the status of the photo

Notes

See the projects/create_photo documentation for more information on how this works.

Photos can be deleted/removed with the photos/delete method.

drafts/list

GET /drafts/patterns/list.json
Get a list of draft patterns that are associated with the current user's pro account(s)

Parameters

Name Type Required Description
business_id Integer If supplied, only return the draft patterns associated with this business

Return Values

Name Type Required Description
businesses Array, Business (list) Yes
draft_patterns Array, DraftPattern (full) Yes

Required permissions

patternstore-read OR patternstore-write

Notes

Returns a list of businesses (ie. pro accounts) that the current user is associated with and the draft patterns associated with the user's businesses (via draft_business_id).

Example

/patterns/drafts/list.json

drafts/publish authenticated

POST /drafts/patterns/{draft_pattern_id}/publish.json
Publish a draft pattern to Ravelry's pattern database.

URI Parameters

Name Type Required Description
draft_pattern_id Integer Yes Draft pattern to publish

Parameters

Name Type Required Description
preview Boolean If set to "true", the pattern will be validated for errors/warnings but not published.

Return Values

Name Type Required Description
draft_pattern DraftPattern (full) Yes Draft pattern
pattern Pattern (full) The published pattern
published Boolean Yes True if the pattern was published succesfully
preview_url String URL to preview the pattern on ravelry.com. Only returned if no errors are present.
errors Array, Hash Yes List of errors. Errors will prevent a pattern from being published.
warnings Array, Hash Yes List of warnings. Warnings will not prevent a pattern from being published.

Notes

Apps should preview and display warnings to the user before publishing a pattern.

drafts/reorder_photos authenticated

POST /drafts/patterns/{draft_pattern_id}/reorder_photos.json
Change order of associated photos

URI Parameters

Name Type Required Description
draft_pattern_id Integer Yes Draft pattern ID

Parameters

Name Type Required Description
sort_order String Yes List of photo IDs, space delimited

Return Values

Name Type Required Description
photos Array, Photo (full) Yes Set of photos with updated ordering

Notes

The first photo becomes the primary photo for the pattern

drafts/show

GET /drafts/patterns/{id}.json
Get draft pattern details

URI Parameters

Name Type Required Description
id Integer Yes Draft pattern to retrieve

Return Values

Name Type Required Description
draft_pattern DraftPattern (full) Yes Draft pattern

Required permissions

patternstore-read OR patternstore-write

Example

/drafts/patterns/100.json

drafts/unpublish authenticated

POST /drafts/patterns/{draft_pattern_id}/unpublish.json
Undo a publish operation. See notes for limitations.

URI Parameters

Name Type Required Description
draft_pattern_id Integer Yes Draft pattern to unpublish

Return Values

Name Type Required Description
draft_pattern DraftPattern (full) Yes Draft pattern

Notes

A draft pattern can be unpublished via the API if:
  • The pattern was published less than 7 days ago
  • The pattern has not been sold or downloaded
  • The pattern has not been linked to a project or queued project

drafts/update authenticated

PUT /drafts/patterns/{draft_pattern_id}.json
Update a draft pattern

URI Parameters

Name Type Required Description
draft_pattern_id Integer Yes Draft pattern to update

Parameters

Name Type Required Description
data DraftPattern (POST) Yes Draft pattern JSON object

Return Values

Name Type Required Description
draft_pattern DraftPattern (full) Yes Draft pattern

extras

extras/create_attachment authenticated

POST /extras/create_attachment.json
Convert an upload into an (image) attachment that can be referenced in fields that accept markdown or HTML

Parameters

Name Type Required Description
image_id Integer Yes Uploaded image to use, created via /upload/image.json

Return Values

Name Type Required Description
image_path String Yes Relative image URL that can be inserted into a forum post or other markdown document

Notes

This method can be used to allow Ravelry Extras (http://ravelry.com/extras) subscribers to host their media files on Ravelry and reference them in forum posts, messages, and other fields that accept images in markdown or HTML. Files that are not images are not accepted and will not be processed.

To test whether or not a user has access to Extras, call this method with no parameters. A HTTP 403 Forbidden return code will indicate that the user does not have this feature.

This method does not return until the image has been processed. This can take a few seconds.

favorites

favorites/add_to_bundle authenticated

POST /people/{username}/favorites/{id}/add_to_bundle.json
Add a favorite record to a bundle

URI Parameters

Name Type Required Description
username String Yes User who owns the favorite record
id Integer Yes Id of the favorite record

Parameters

Name Type Required Description
bundle_id Integer Yes Id of the bundle the favorite should be added to

Return Values

Name Type Required Description
bookmark Bookmark (full) Yes The bundled record

favorites/create authenticated

POST /people/{username}/favorites/create.json
Create favorite record

URI Parameters

Name Type Required Description
username String Yes User who owns the favorite record

Parameters

Name Type Required Description
data Bookmark (POST) Yes Bookmark (favorite) JSON object

Return Values

Name Type Required Description
bookmark Bookmark (full) Yes The newly created record

Example

/people/username/favorites/create.json { "type": "pattern", "favorited_id": 1, "comment": "This is a comment" }

favorites/delete authenticated

DELETE /people/{username}/favorites/{id}.json
Delete a favorite record

URI Parameters

Name Type Required Description
username String Yes User who owns the favorite record
id Integer Yes Id of the favorite record that should be deleted

Return Values

Name Type Required Description
bookmark Bookmark (full) Yes The deleted record

favorites/list authenticated

GET /people/{username}/favorites/list.json
Get favorite list

URI Parameters

Name Type Required Description
username String Yes User to retrieve projects from

Parameters

Name Type Required Description
types Array, String Space delimited list of types of favorites to retrieve. Accepted options: project, pattern, yarn, stash, forumpost, designer, yarnbrand, yarnshop, bundle. Defaults to all types.
query String Search query for full text search. Cannot be combined with "tag" parameter.
deep_search Boolean Full text search should search inside text of favorited items (notes, etc). Defaults to false.
tag String Search query for tag search. Cannot be combined with "query" parameter.
page Integer Result page to retrieve. Defaults to 1 (the first page).
page_size Integer Defaults to 25. Maximum size accepted = 100

Return Values

Name Type Required Description
favorites Array, Bookmark (list) Yes Matching favorites
paginator Paginator Yes Pagination object with total results, pages

Notes

Favorites are returned in ordered by creation date, descending. The favorited item is nested in the JSON result under the key "favorited". If you request a mix of different types of favorites, you can use the "type" key to determine the type of favorite that you are receiving.

Example

/people/username/favorites/list.json

favorites/remove_from_bundle authenticated

POST /people/{username}/favorites/{id}/remove_from_bundle.json
Remove a favorite record from a bundle

URI Parameters

Name Type Required Description
username String Yes User who owns the favorite record
id Integer Yes Id of the favorite record

Parameters

Name Type Required Description
bundle_id Integer Yes Id of the bundle the favorite should be removed from

Return Values

Name Type Required Description
bookmark Bookmark (full) Yes The unbundled record

favorites/show authenticated

GET /people/{username}/favorites/{id}.json
Retrieve a favorite record

URI Parameters

Name Type Required Description
username String Yes User who owns the favorite record
id Integer Yes ID of the favorite to retrieve

Return Values

Name Type Required Description
bookmark Bookmark (full) Yes The newly created record

Example

/people/username/favorites/42.json

favorites/update authenticated

POST /people/{username}/favorites/{id}.json
Update a favorite record

URI Parameters

Name Type Required Description
username String Yes User who owns the favorite record
id Integer Yes Id of the favorite record that should be updated

Parameters

Name Type Required Description
data Bookmark (POST) Yes Bookmark (favorite) JSON object

Return Values

Name Type Required Description
bookmark Bookmark (full) Yes The updated record

Example

/people/username/favorites/42.json { "comment": "This is an updated comment" }

fiber

fiber/comments

GET /people/{username}/fiber/{id}/comments.json
Retrieve a stashed fiber's comments

Parameters

Name Type Required Description
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Defaults to 25 comments per page. Maximum is 100.
sort String Sort order. Options are: time (and time_ for a descending sort)

Return Values

Name Type Required Description
comments Array, Comment Yes Comments with nested replies.
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Comments have one level of nesting. Replies from the owner of the stashed fiber may be nested under the "replies" attribute.

fiber/create authenticated

POST /people/{username}/fiber/create.json
Create fiber stash record

URI Parameters

Name Type Required Description
username String Yes User to create fiber stash for

Parameters

Name Type Required Description
data FiberStash (POST) Yes Fiber Stash JSON object

Return Values

Name Type Required Description
fiber_stash FiberStash (full) Yes Fiber Stash

Example

/people/username/fiber/create.json { "yarn_id": 1, "dye_lot": "42" }

fiber/create_photo authenticated

POST /people/{username}/fiber/{id}/create_photo.json
Add a photo to a stashed fiber (using an uploaded image or URL as a source)

URI Parameters

Name Type Required Description
username String Yes Username of the user who owns the fiber stash entry
id String Yes Fiber Stash ID

Parameters

Name Type Required Description
image_id Integer Uploaded image to use, created via /upload/image.json
source_url Integer URL of the image to use (preferably high-res)

Return Values

Name Type Required Description
status_token String Yes Token that can be used to check the status of the photo

Notes

See the projects create_photo documentation for more information on how this works.

fiber/delete authenticated

DELETE /people/{username}/fiber/{id}.json
Permanently delete a fiber stash entry

URI Parameters

Name Type Required Description
username String Yes User who owns the fiber stash entry
id Integer Yes Fiber stash ID

Return Values

Name Type Required Description
fiber_stash FiberStash (full) Yes Fiber stash that was deleted

fiber/show authenticated

GET /people/{username}/fiber/{id}.json
Get fiber stash record

URI Parameters

Name Type Required Description
username String Yes User to retrieve stash from
id Integer Yes Stash to retrieve

Return Values

Name Type Required Description
fiber_stash FiberStash (full) Yes Stash
user User (small) Yes User

Example

/people/username/fiber/989.json

fiber/update authenticated

POST /people/{username}/fiber/{id}.json
Update an existing fiber stash record

URI Parameters

Name Type Required Description
username String Yes User who owns the fiber entry
id Integer Yes ID of the fiber stash entry to update

Parameters

Name Type Required Description
data FiberStash (POST) Yes Fiber Stash JSON object

Return Values

Name Type Required Description
fiber_stash FiberStash (full) Yes Fiber Stash

Example

/people/username/fiber/989.json { dye_lot": "43" }

fiber_attribute_groups

fiber_attribute_groups/list

GET /fiber_attribute_groups/list.json
Retrieve list of fiber attribute groups

Return Values

Name Type Required Description
fiber_attribute_groups Array, FiberAttributeGroup Yes All fiber attribute groups

Notes

Fiber attribute groups seldom change, I'd recommend caching them for up to 24 hours. This method does not require an API key.

Example

/fiber_attribute_groups.json

forum_posts

forum_posts/show authenticated

GET /forum_posts/{forum_post_id}.json
Get single forum post

URI Parameters

Name Type Required Description
forum_post_id Integer Yes Forum post to retrieve

Return Values

Name Type Required Description
forum_post ForumPost (full) Yes Forum post

forum_posts/unread

GET /forum_posts/unread.json
Get list of unread posts, across all forums

Parameters

Name Type Required Description
include Array, String Extra result parts to include. Space delimited. Accepted options: vote_totals, user_votes
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Page size. Defaults to 25.

Return Values

Name Type Required Description
posts Array, ForumPost (list) Yes List of posts
vote_totals ForumMarkers vote_totals are returned if they are requested with the "include" parameter
user_votes Array, String user_votes are returned if they are requested with the "include" parameter
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

this is being called too much

Example

/forum_posts/unread.json

forum_posts/update authenticated

POST /forum_posts/{forum_post_id}.json
Update a forum post

URI Parameters

Name Type Required Description
forum_post_id Integer Yes Forum post to update

Parameters

Name Type Required Description
body String Yes New forum post body

Return Values

Name Type Required Description
forum_post ForumPost (full) Yes Updated forum post

forum_posts/vote authenticated

GET /forum_posts/{forum_post_id}/vote.json
Update your vote on one of the forum post voting buttons

URI Parameters

Name Type Required Description
forum_post_id Integer Yes Forum post to vote on

Parameters

Name Type Required Description
vote Boolean Yes Your vote. Accepted values are 0 and 1: 1 to set your vote, 0 to clear it
type String Yes Type of vote to cast. Accepted options: interesting, educational, funny, agree, disagree, love

Return Values

Name Type Required Description
vote_totals ForumMarkers Yes Totals (grouped by by type) of all votes on this post
user_votes Array, String Yes List of the types that the current user has voted on

Notes

Note that voting is rate limited to prevent automated voting. Normal activity will not trigger it but if you provide features like "vote all" (which is discouraged), you will likely run into rate limiting.

Example

POST /forum_posts/1000/vote.json type=funny&vote=1

forums

forums/filtered_topics authenticated

GET /forums/filtered_topics.json
Filter topics across all forums/groups to find those that are relevant to the authenticated user

Parameters

Name Type Required Description
status String Yes One of: mine, reading, posting, watching, ignoring
sort String One of: started, replied, posts, topic. Defaults to "replied"
page Integer Yes Result page to retrieve. Defaults to first page.
page_size Integer Yes Defaults to 25, maximum is 100.

Return Values

Name Type Required Description
topics Array, Topic (list) Yes List of matching topics
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

This API call is analogous to the https://www.ravelry.com/discuss/browse page on Ravelry

Accepted statuses:
  • mine: threads that the user has started
  • reading: threads that the user has viewed
  • posting: threads that the user has posted in
  • watching: watched threads
  • ignoring: ignored threads
Accepted sort orders. Ascending/descending and multiple selections are supported. See Sorting and Pagination
  • started: time since the topic was started
  • replied: time since the latest reply to the topic
  • posts: number of posts in the topic
  • topic: title of the topic

Example

/forums/filtered_topics.json?status=mine

forums/sets authenticated

GET /forums/sets.json
Get forum sets for current user (or default set)

Return Values

Name Type Required Description
forum_sets Array, ForumSet Yes Forum sets

Example

/forums/sets.json

forums/topics authenticated

GET /forums/{forum_id}/topics.json
Get topic list for a specific forum, personalize for the authenticated user

URI Parameters

Name Type Required Description
forum_id Integer Yes Forum to retrieve topics from

Parameters

Name Type Required Description
page Integer Yes Result page to retrieve. Defaults to first page.

Return Values

Name Type Required Description
forum Forum (list) Yes Selected forum
topics Array, Topic (list) Yes List of topics
paginator Paginator Yes Pagination object with total results, pages, etc

Example

/forums/3/topics.json

friends

friends/activity authenticated

GET /people/{username}/friends/activity.json
Retrieve recent friends' activity

URI Parameters

Name Type Required Description
username String Yes Friends will be selected from this user

Parameters

Name Type Required Description
page Integer Result page to retrieve. Defaults to 1 (the first page).
page_size Integer Defaults to 25. Maximum size accepted = 50
activity_type_keys String Space delimited list of activity types. Currently accepted types: added-project-photo, added-stash-photo, queued-pattern, added-favorite, added-handspun-photo

Return Values

Name Type Required Description
activities Array, Activity (list) Yes List of activity records
paginator Paginator Yes Pagination object with total results, pages

Notes

A feed of friends' activity on Ravelry. This information is displayed on the "people" tab on the site as well as in the "Friends" section of users' Ravelry notebook. Note: activity that is older than 30 days is not available.

Example

GET /people/username/friends/activity.json?activity_type_keys=added-project-photo+added-stash-photo

friends/create authenticated

POST /people/{username}/friends/create.json
Add a friend

URI Parameters

Name Type Required Description
username String Yes User who owns the friendship record (ie. the currently logged in user)

Parameters

Name Type Required Description
friend_user_id Integer Yes User ID of the user who should be added as a friend

Return Values

Name Type Required Description
friendship Friendship (full) Yes The newly created friendship record

Example

POST /people/username/friends/create.json friend_user_id=1

friends/destroy authenticated

POST /people/{username}/friends/{id}/destroy.json
Delete a friendship record

URI Parameters

Name Type Required Description
username String Yes User who owns the friendship record (ie. the currently logged in user)
id Integer Yes ID of the friendship record that should be deleted (not the user ID)

Return Values

Name Type Required Description
friendship Friendship (full) Yes The deleted friendship record

Example

POST /people/username/friends/42/destroy.json

friends/list authenticated

GET /people/{username}/friends/list.json
Get friend list

URI Parameters

Name Type Required Description
username String Yes User to retrieve projects from

Return Values

Name Type Required Description
collections Array, Collection Friend sets
friendships Array, Friendship (list) Yes All friendships

Example

/people/username/friends/list.json

groups

groups/groups

GET /groups/search.json
Search the group directory

Parameters

Name Type Required Description
query String Search term for fulltext searching
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Defaults to 50 results per page.
sort String Sort order. Options are: best, added, favorites

Return Values

Name Type Required Description
groups Array, Group (list) Yes Matching groups
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Note that you may also use any of the parameters for filters that are available in the on-site group search.

Example

/groups/search.json?query=wollmeise

in_store_sales

in_store_sales/add

POST /in_store_sales/carts/#{id}/add.json
Add a product to a cart

URI Parameters

Name Type Required Description
id Integer Yes Cart ID

Parameters

Name Type Required Description
product_id Integer Yes Product ID. An error will be returned if this product is not available for sale.

Return Values

Name Type Required Description
combined_cart CombinedCart (full) Yes the newly updated cart

in_store_sales/add_by_pattern

POST /in_store_sales/carts/#{id}/add_by_pattern.json
Add a product to a cart using a pattern ID of a related pattern.

URI Parameters

Name Type Required Description
id Integer Yes Cart ID

Parameters

Name Type Required Description
pattern_id Integer Yes Pattern ID. An error will be returned if the pattern is not associated with a single product or if the product is not available for sale.

Return Values

Name Type Required Description
combined_cart CombinedCart (full) Yes the newly updated cart

Notes

Note that this API method is only useful to retail shops who are participating in the In Store Sales program.

in_store_sales/checkout

POST /in_store_sales/carts/#{id}/checkout.json
Checkout a cart. The wholesale price will be added to your monthly bill.

URI Parameters

Name Type Required Description
id Integer Yes Cart ID

Parameters

Name Type Required Description
disable_email_notification Boolean Defaults to false (0) Set to 1 to prevent Ravelry from sending out a download receipt to the purchaser via email

Return Values

Name Type Required Description
in_store_sales Array, InStoreSale (receipt) Yes the completed sales records (including any digital deliveries)

Notes

This completes a purchase. The wholesale price will be added to your monthly bill. Note that this API method is only useful to retail shops who are participating in the In Store Sales program.

in_store_sales/create

POST /in_store_sales/carts/create.json
Create a new cart

Parameters

Name Type Required Description
customer_name String
customer_email_address String Email address for email notification
customer_user_id String Ravelry user ID

Return Values

Name Type Required Description
combined_cart CombinedCart (full) Yes the newly created cart

Notes

At minimum, either customer_email address or customer_user_id must be supplied. Note that this API method is only useful to retail shops who are participating in the In Store Sales program.

in_store_sales/show

GET /in_store_sales/carts/{id}.json
View a previously created cart

URI Parameters

Name Type Required Description
id Integer Yes

Return Values

Name Type Required Description
combined_cart CombinedCart (full) Yes the cart

Notes

Note that this API method is only useful to retail shops who are participating in the In Store Sales program.

languages

languages/languages

GET /languages/list.json
Retrieve list of available languages

Return Values

Name Type Required Description
languages Array, Language Yes All languages

Notes

Note that there is a special language - "Universal"/"Universal - no written language". The "universal" attribute will be set to true for this language.

Example

/languages/list.json

library

GET /people/{username}/library/search.json
Search a library

URI Parameters

Name Type Required Description
username String Yes User to search

Parameters

Name Type Required Description
query String Full text search string
query_type String One of "patterns" (to search pattern full text) or "tags" to search tags in queued items
type String Type of source. Accepted options: book, magazine, booklet, pattern, pdf
sort String Sort order. Accepted options: title, added, published, author. Multiple space-delimited options are accepted.
page Integer Result page to retrieve. Defaults to 1 (the first page).
page_size Integer Number of results per page. Defaults to 100

Return Values

Name Type Required Description
paginator Paginator Yes Pagination object with total results, pages
volumes Array, Volume (list) Yes Matching volumes

Notes

Note that PDF patterns (type=pdf, Ravelry downloads) will only appear in search results if you are searching your own library.

Example

/people/username/library/search.json?type=book&query=Dogs

messages

messages/archive

POST /messages/{id}/archive.json
Archive a message

URI Parameters

Name Type Required Description
id Integer Yes Message ID to archive

Return Values

Name Type Required Description
message Message (full) Yes Message

Required permissions

message-write

Notes

Moves a message from "inbox" to the "saved" box

Example

/messages/22237804/archive.json

messages/create

POST /messages/create.json
Create and send a private message to another Ravelry user

Parameters

Name Type Required Description
data Message (POST) Yes Message JSON object

Return Values

Name Type Required Description
message Message (full) Yes The newly created message

Required permissions

message-write

Notes

Creates and immediately sends a message. Messages cannot be edited or changed after they are created. This method requires message-write permission This method will return a 403 status code with errors if either the sender or recipient has Ravelry messaging disabled in their profile.

messages/delete

DELETE /messages/{id}.json
Delete a message

URI Parameters

Name Type Required Description
id Integer Yes Message ID to delete

Return Values

Name Type Required Description
message Message (full) Yes Message

Required permissions

message-write

Example

DELETE /messages/22237804.json

messages/list authenticated

GET /messages/list.json
Get message list

Parameters

Name Type Required Description
folder String Yes Folder to list - one of: inbox, sent, archived
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Size of result pages. Defaults to 100.
search String Search term for fulltext searching messages
unread_only Boolean Set to 1 to only return unread messages
output_format String Output format. Accepted options: list, full. Defaults to list (Message#list)
sort String Sort order. Accepted options: "time" (oldest first), "time_" (descending / newest first). Defaults to "time_"

Return Values

Name Type Required Description
messages Array, Message (list) Yes Messages
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Smaller page sizes are recommended if you are using the "full" output format. It's not uncommon for users to have very large inboxes or even very large numbers messages that have been marked as unread.

Example

/messages/list.json?folder=inbox&format=full&unread_only=1&page_size=20

messages/mark_read authenticated

POST /messages/{id}/mark_read.json
Mark a message as read

URI Parameters

Name Type Required Description
id Integer Yes Message ID to mark

Return Values

Name Type Required Description
message Message (full) Yes Message

Example

/messages/22237804/mark_read.json

messages/mark_unread authenticated

POST /messages/{id}/mark_unread.json
Mark a message as unread

URI Parameters

Name Type Required Description
id Integer Yes Message ID to mark

Return Values

Name Type Required Description
message Message (full) Yes Message

Example

/messages/22237804/mark_unread.json

messages/reply

POST /messages/{id}/reply.json
Reply to a private message to another Ravelry user, same as create but links the messages together as a conversat

URI Parameters

Name Type Required Description
id Integer ID of the message being replied to. Must be a message that has the current user listed as the recipient

Parameters

Name Type Required Description
data Message (POST) Yes Message JSON object

Return Values

Name Type Required Description
message Message (full) Yes The newly created message

Required permissions

message-write

Notes

Creates and immediately sends a message. Messages cannot be edited or changed after they are created. This method requires message-write permission This method will return a 403 status code with errors if either the sender or recipient has Ravelry messaging disabled in their profile.

messages/show authenticated

GET /messages/{id}.json
Get message

URI Parameters

Name Type Required Description
id Integer Yes Message ID to retrieve

Return Values

Name Type Required Description
message Message (full) Yes Message

Example

/messages/22237804.json

messages/unarchive

POST /messages/{id}/unarchive.json
Archive a message

URI Parameters

Name Type Required Description
id Integer Yes Message ID to unarchive

Return Values

Name Type Required Description
message Message (full) Yes Message

Required permissions

message-write

Notes

Moves a message from "saved" back to "inbox"

Example

/messages/22237804/unarchive.json

needles

needles/list authenticated

GET /people/{username}/needles/list.json
Get needle records

URI Parameters

Name Type Required Description
username String Yes User to retrieve needles for

Return Values

Name Type Required Description
needle_records Array, NeedleRecord (full) Yes Needle records

needles/sizes authenticated

GET /needles/sizes.json
Get available sizes for each needle type

Parameters

Name Type Required Description
craft String Type of tool to return. "crochet" for hooks only, "knitting" for knitting needles only. Default is empty (return both)

Return Values

Name Type Required Description
needle_sizes Array, NeedleSize (list) Yes Needle sizes

needles/types authenticated

GET /needles/types.json
Get needle types

Return Values

Name Type Required Description
needle_type Array, NeedleType (full) Yes Needle types

packs

packs/create authenticated

POST /packs/create.json
Create pack

Parameters

Name Type Required Description
data Pack (POST) Yes Pack JSON object

Return Values

Name Type Required Description
pack Pack (full) Yes Pack

packs/delete authenticated

DELETE /packs/{pack_id}.json
Delete pack

URI Parameters

Name Type Required Description
pack_id Integer Yes Pack to delete

Return Values

Name Type Required Description
pack Pack (full) Yes Pack that was deleted

packs/show authenticated

GET /packs/{pack_id}.json
Get single pack

URI Parameters

Name Type Required Description
pack_id Integer Yes Pack to retrieve

Return Values

Name Type Required Description
pack Pack (full) Yes Pack

packs/update authenticated

PUT /packs/{pack_id}.json
Update a pack

URI Parameters

Name Type Required Description
pack_id Integer Yes Pack to update

Parameters

Name Type Required Description
data Pack (POST) Yes Pack JSON object

Return Values

Name Type Required Description
pack Pack (full) Yes Pack

Notes

Packs must be associated with either a project or stash entry.

If your pack is associated with a stash entry because you want to tie a portion of that stash entry to a project, then nearly all of the attributes are inherited from that stash entry. For these packs, you can set weights and lengths to record how much yarn is allocated to a project (total_length, total_weight) Units will match the stash's units.

pages

pages/show authenticated

GET /pages/{id}.json
Get page

URI Parameters

Name Type Required Description
id Integer Yes Page to retrieve

Return Values

Name Type Required Description
page Page (full) Yes Page

Example

/pages/1.json

pages/update authenticated

POST /pages/{id}.json
Update page

URI Parameters

Name Type Required Description
id Integer Yes Page to update

Parameters

Name Type Required Description
page.title String Yes Page title
page.body String Yes Page body

Return Values

Name Type Required Description
page Page (full) Yes Updated page

Example

/pages/1.json?name=page+title&body=page+body

pattern_attributes

pattern_attributes/list

GET /pattern_attributes/groups.json
List the current pattern attributes

Return Values

Name Type Required Description
attribute_groups Array, AttributeGroup (list) Yes List of all current pattern attributes, organized into groups that contain attributes and possibly sub-groups

Notes

Pattern attributes seldom change, I'd recommend caching them for up to 24 hours. This method does not require an API key.

pattern_categories

pattern_categories/list

GET /pattern_categories/list.json
List the current pattern categories

Return Values

Name Type Required Description
pattern_categories Array, PatternCategory (list) Yes List of all pattern categories

Notes

Pattern categories seldom change, I'd recommend caching them for up to 24 hours. This method does not require an API key.

pattern_source_types

pattern_source_types/list

GET /pattern_source_types/list.json
List the current pattern source types

Return Values

Name Type Required Description
pattern_source_types Array, PatternSourceType (list) Yes List of all pattern categories

Notes

Pattern source types seldom change. This method does not require an API key.

pattern_sources

pattern_sources/patterns authenticated

GET /pattern_sources/{id}/patterns.json
Get the set of patterns that a given source contains

URI Parameters

Name Type Required Description
id String Yes ID of the pattern source

Parameters

Name Type Required Description
page Integer Yes Result page to retrieve. Defaults to 1 (the first page).
page_size Integer Yes Defaults to 50 results per page.

Return Values

Name Type Required Description
patterns Array, Pattern (source_list) Yes List of patterns contained in this source
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

About 1% of pattern sources contain more than 50 patterns.

Example

/pattern_sources/1/patterns.json
GET /pattern_sources/search.json
Search pattern source database

Parameters

Name Type Required Description
query String Search term for fulltext searching patterns
page Integer Result page to retrieve. Defaults to first page.
page_number Integer Number of results to retrieve. Defaults to 100.

Return Values

Name Type Required Description
pattern_sources Array, PatternSource (list) Yes Matching pattern sources
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Note that you may also use any of the (many) parameters for filters that are available in the on-site pattern search.

Example

/pattern_sources/search.json?isbn=978-0984572601

pattern_sources/show

GET /pattern_sources/{id}.json
Get pattern source details

URI Parameters

Name Type Required Description
id Integer Yes Pattern source to retrieve

Return Values

Name Type Required Description
pattern_source PatternSource (full) Yes

Example

/pattern_sources/573.json

patterns

patterns/comments

GET /patterns/{id}/comments.json
Retrieve a pattern's comments

Parameters

Name Type Required Description
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Defaults to 25 comments per page. Maximum is 100.
sort String Sort order. Options are: time, helpful (and time_, helpful_ for a descending sort)
include Array, String Extra result parts to include. Space delimited. Accepted options: highlighted_project

Return Values

Name Type Required Description
comments Array, Comment Yes Comments with nested replies.
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Comments have one level of nesting. Replies from the owner of the pattern may be nested under the "replies" attribute.

patterns/create_photo authenticated

POST /patterns/{id}/create_photo.json
Add a photo to a pattern (using an uploaded image or URL as a source)

URI Parameters

Name Type Required Description
id Integer Yes Pattern ID

Parameters

Name Type Required Description
image_id Integer Uploaded image to use, created via /upload/image.json
source_url String URL of the image to use (preferably high-res)

Return Values

Name Type Required Description
status_token String Yes Token that can be used to check the status of the photo

Required permissions

pattern-write OR patternstore-write

Notes

This method will create a new photo using one of two sources:

  • If image_id is supplied, the photo will be created from an image that was uploaded via /upload/image.json
  • If source_url is supplied, the source image will be retrieved from a URL

This method returns immediately. The image will be added to the pattern as a photo once it has been processed and resized into the various sizes used by Ravelry. Any size image is accepted. Ravelry will store the original or a 1600x1600 version (whichever is smaller) in addition to all of the necessary thumbnails.

Photo creation time varies depending on the size of the image. It should complete within a few seconds. If you'd like to monitor the status of the process, you can use the status_token that is returned with /photos/status.json

patterns/highlights

GET /patterns/highlights.json
Get pattern highlights for the current user

Parameters

Name Type Required Description
days Integer Yes Number of days of highlights to retrieve. Default = 30 (ie. 30 days ago to present), maximum = 90

Return Values

Name Type Required Description
timeline_entries Object Yes Timeline entries contain a timeline_date (Date), pattern (Pattern#full), and explanatory reasons for inclusion.

Example

/patterns/highlights.json

patterns/patterns

GET /patterns.json
Get pattern details for multiple patterns

Parameters

Name Type Required Description
ids Integer Yes Space delimited list of pattern IDs to retrieve

Return Values

Name Type Required Description
patterns Object Yes Map of `Pattern#full` results, indexed by pattern ID

Example

/patterns.json?ids=600+601

patterns/projects

GET /patterns/{id}/projects.json
Retrieve the list of projects that are linked to this pattern

URI Parameters

Name Type Required Description
id Integer Yes ID of the pattern

Parameters

Name Type Required Description
query String Supply a query to optionally full text search inside of linked projects
sort String Sort order. Accepted options are: favorites", and "completed". Default is "completed".
photoless Boolean Set to "1" if want to return results that do not have a photo
page Integer Result page to retrieve. Defaults to 1 (the first page).
page_size Integer Yes Number of results per page. Defaults to 100

Return Values

Name Type Required Description
projects Array, Project Yes List of projects that are linked to the pattern
paginator Paginator Yes Pagination object with total results, pages

Notes

The default sort ("completed") is completion date, start date in decending order. If you supply a sort parameter, your selected sort will be applied before ordering by date. (For more complex sort/filter options see the forthcoming project search API)

Example

/patterns/573/projects.json

patterns/reorder_photos authenticated

POST /patterns/{id}/reorder_photos.json
Change order of associated photos

URI Parameters

Name Type Required Description
id Integer Yes Pattern pattern ID

Parameters

Name Type Required Description
sort_order String Yes List of photo IDs, space delimited

Return Values

Name Type Required Description
photos Array, Photo (full) Yes Set of photos with updated ordering

Required permissions

pattern-write OR patternstore-write

Notes

The first photo becomes the primary photo for the pattern
GET /patterns/search.json
Search pattern database

Parameters

Name Type Required Description
query String Search term for fulltext searching patterns
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Number of results to retrieve. Defaults to 100.
personal_attributes Boolean set to 1 if you would like to return the personal_attributes hash in the result objects

Return Values

Name Type Required Description
patterns Array, Pattern (list) Yes Matching patterns
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Note that you may also use any of the (many) parameters for filters that are available in the on-site pattern search. To filter by a list of pattern IDs, use the pattern_id parameter with a pipe (|) delimited list of integer IDs.

Example

/patterns/search.json?query=cowl

patterns/show

GET /patterns/{id}.json
Get pattern details

URI Parameters

Name Type Required Description
id Integer Yes Pattern to retrieve

Return Values

Name Type Required Description
patterns Pattern (full) Yes

Notes

If you'd like to retrieve multiple patterns in one call, you can use /patterns.json to do that.

You can directly link to a pattern page with the "buy" box open (if the pattern has a product for sale) by constructing a URL like "ravelry.com/patterns/library/permalink?buy=1". If it is known that the user has a Ravelry account, and you would like to force a login, also add "guest_buy=0" to the query parameters.

Example

/patterns/573.json

patterns/update

PUT /patterns/{id}.json
Update a pattern

URI Parameters

Name Type Required Description
pattern_id Integer Yes Pattern to update

Parameters

Name Type Required Description
data Pattern (POST) Yes Pattern JSON object

Return Values

Name Type Required Description
pattern Pattern (full) Yes Updated pattern

Required permissions

pattern-write OR patternstore-write

Notes

This method updates a pattern. Currently, a pattern can only be updated by the user who created it.

The required scopes (pattern-write or patternstore-write) are only available to whitelisted apps.

If validation errors occur, a 400 Bad Request will be returned along with the errors.

people

people/show authenticated

GET /people/{id}.json
Get user profile

URI Parameters

Name Type Required Description
id String Yes Username of user to lookup. Integer identifiers are also accepted.

Return Values

Name Type Required Description
user User (full) Yes User

Example

/people/bob.json

people/update authenticated

POST /people/{id}.json
Update user profile

URI Parameters

Name Type Required Description
id String Yes Username of user to update. Integer identifiers are also accepted.

Parameters

Name Type Required Description
data User (POST) Yes User JSON object

Return Values

Name Type Required Description
user User (full) Yes Newly updated user

Required permissions

profile-write

Example

/people/username/stash/96647.json { "about_me": "It's me, bob" }

photos

photos/delete authenticated

DELETE /photos/{id}.json
Delete photo

URI Parameters

Name Type Required Description
id String Yes Photo to delete

Return Values

Name Type Required Description
photo Photo (full) Yes Photo that was deleted

photos/dimensions authenticated

GET /photos/dimensions.json
Get photo thumbnail dimensions

URI Parameters

Name Type Required Description
photo_id_list String Yes Space delimited list of photo IDs to look up.

Return Values

Name Type Required Description
dimensions Object Yes Photo dimension information, with photo IDs as keys. See notes.

Notes

NOTE: if you only need the aspect ratio, that is already available in most Photo responses Photo dimensions are not currently returned as part of `Photo` results. You can use this method to retrieve that information. For each photo looked up, the result will contain the height and width, width, and height for each size. The possible sizes that will be returned for each photo are:
  • small : 240 px on the longest side
  • small2: 320 px on the longest side
  • medium: 500 px on the longest side
  • medium2: 640 px on the longest side, may not be present for small photos

Example

/photos/dimensions.json?photo_id_list=42+43

photos/sizes authenticated

GET /photos/{id}/sizes.json
Get available photo sizes

URI Parameters

Name Type Required Description
id Integer Yes Photo to lookup

Return Values

Name Type Required Description
photo Photo (full) Yes Photo
sizes Array, PhotoSize Yes Photo sizes

Notes

NOTE: /photos/dimensions.json will return very similar information and it can retrieve data for multiple photos at once. You may want to use that method instead. This method will be most useful when you are looking for the large size in order to zoom in on a photo. The possible size keys returned are:
  • square : always 75x75
  • thumbnail : 100 px on the longest side
  • small : 240 px on the longest side
  • medium: 500 px on the longest side
  • medium2: 640 px on the longest side, optional
  • large: 1000 - 1600 px on the longest side, optional
This method may be relatively slow (several tenths of a second) if the dimensions for a given photo have never been requested

Example

/photos/1/sizes.json

photos/status authenticated

GET /photos/status.json
Get the status of a photo creation that is in progress

Parameters

Name Type Required Description
status_token String Yes Status token that you received when creating the photo

Return Values

Name Type Required Description
photo Photo (full) Yes Photo, if the process is complete
progress Integer Yes Current progress, from 1..100
complete Boolean Yes true if the photo creation has completed
failed Boolean Yes true if the photo creation was not possible (most common cause is an unsupported file type)

Example

/photos/status.json?status_token=foo

photos/update authenticated

POST /photos/{id}.json
Update photo attributes

URI Parameters

Name Type Required Description
id String Yes Photo ID

Parameters

Name Type Required Description
x_offset Integer X offset for centered photo. See notes.
y_offset Integer Y offset for centered photo. See notes.
copyright_notice String Copyright line. See notes.
caption String

Return Values

Name Type Required Description
photo Photo (full) Yes Photo object, after updates have been applied

Notes

The offsets are used to place the Photo's small image (small_url) in a 170x170 pixel square frame. By default, they are calculated such that the photo is centered in this frame.

If you prefer a larger thumbnail, you can approximate the center within a few pixels by using the medium_url image and a 350 pixel frame and doubling the offsets.

The "copyright_notice" field is displayed in various places on Ravelry underneath the photo. It is not required, and it will normally be set to the member's username for stash and project photos.

The "caption" field is not currently displayed anywhere on Ravelry

product_attachments

product_attachments/delete authenticated

DELETE /product_attachments/{id}.json
Remove a product attachment from a product

URI Parameters

Name Type Required Description
id Integer Yes ID of the product attachment that should be deleted

Return Values

Name Type Required Description
product_attachment ProductAttachment (full) Yes The deleted record

Notes

This method requires the patternstore-write permission
POST /product_attachments/{id}/generate_download_link.json
Generate an expiring link that can be used to directly download the PDF associated with a product attachment

Parameters

Name Type Required Description
id Integer Yes ID of the product attachment

Return Values

Name Type Required Description
download_link DownloadLink Yes

Notes

This method requires the library-pdf permission (for normal users) or the patternstore-pdf permission (for pattern sellers) Note that OAuth keys that include the library-pdf scope will expire much faster than usual. This method will return a 429 Too Many Requests if the user has exceeded their daily request limit for this method. The daily limit is currently set to 100 requests.

product_attachments/show authenticated

GET /product_attachments/{id}.json
Retrieve a product attachment

URI Parameters

Name Type Required Description
id Integer Yes ID of the product attachment

Return Values

Name Type Required Description
product_attachment ProductAttachment (full) Yes The requested product attachment

Notes

This method requires the patternstore-write permission

product_attachments/update authenticated

POST /product_attachments/{id}.json
Update a product attachment

URI Parameters

Name Type Required Description
id Integer Yes ID of the product attachment

Return Values

Name Type Required Description
product_attachment ProductAttachment (full) Yes The updated product attachment

Notes

This method requires the patternstore-write permission

product_attachments/upload authenticated

POST /product_attachments/upload.json
Upload a new product attachment

Parameters

Name Type Required Description
product_id Integer Yes ID of the product to which the attachment should be added
file File Yes The PDF file to upload

Return Values

Name Type Required Description
success Boolean Yes Whether the upload was successful. See notes.

Notes

This method requires the patternstore-write permission.

This is an "upload" method and should be implemented as multipart form post (multipart/form-data). A "product_id" parameter is required and the name of the file parameter should be "file".

Note: there is not currently a way to be notified of upload progress. However, you can poll the product and your new attachment will appear inside the product when it is ready (usually within seconds)

products

products/activate

POST /products/{id}.json
Activate a product (make it available for sale)

URI Parameters

Name Type Required Description
id Integer Yes Product ID

Return Values

Name Type Required Description
product Product (full) Yes Product

Notes

This method requires the patternstore-write permission.

products/attachments

GET /products/{id}/attachments.json
Retrieve attached documents for this product

URI Parameters

Name Type Required Description
id Integer Yes Product ID

Return Values

Name Type Required Description
product_attachments Array, ProductAttachment Yes Attachments for this product

Notes

This method requires the patternstore-read permission.

Example

/products/1970/attachments.json

products/create

POST /products/create.json
Create a new product

Parameters

Name Type Required Description
store_id Integer Yes Store ID for the store that will contain the new product
pattern_id Integer see notes
pattern_source_id Integer see notes
draft_pattern_id Integer see notes

Return Values

Name Type Required Description
product Product (full) Yes Product

Notes

This method creates a new product stub based on the supplied draft pattern, pattern or pattern source. Only one of the three parameters should be supplied. Once created, the product can be updated with price info, attachments, and activated. This method requires the patternstore-write permission.

products/deactivate

POST /products/{id}.json
Deactivate a product (make it unavailable for sale)

URI Parameters

Name Type Required Description
id Integer Yes Product ID

Return Values

Name Type Required Description
product Product (full) Yes Product

Notes

This method requires the patternstore-write permission.

products/loveknitting/export authenticated

GET /products/loveknitting/export.json
Get loveknitting data for a product

Parameters

Name Type Required Description
product_id_list String Yes Space delimited list of product IDs to export

Return Values

Name Type Required Description
products Array, LoveknittingProduct (full) Yes List of objects containing oroduct and pattern attributes for loveknitting

Required permissions

patternstore-pdf

products/loveknitting/update_status authenticated

POST /products/{id}/loveknitting/update_status.json
Update status of an associated loveknitting product

Parameters

Name Type Required Description
product_id Integer Yes Ravelry ID of product to update
loveknitting_identifier String ID of the product within loveknitting
pdf_id String The PDF ID from /products/loveknitting/export.json, if a provided PDF is being used on LK
price String current LK price of the product
currency String current LK currency of the product (always GBP at the moment)
status String One of: pending, approved, rejected, deleted, published, disabled

Return Values

Name Type Required Description
success Boolean Yes

Notes

The Loveknitting API key has permission to use this method. Current status codes are: * pending * approved * rejected * deleted

products/show

GET /products/{id}.json
Retrieve product information

URI Parameters

Name Type Required Description
id Integer Yes Product ID

Return Values

Name Type Required Description
product Product Yes Product

Notes

This method requires the patternstore-read permission.

Example

/products/1970.json

products/update

POST /products/{id}.json
Update product information

URI Parameters

Name Type Required Description
id Integer Yes Product ID

Parameters

Name Type Required Description
data Product (POST) Yes Product JSON object

Return Values

Name Type Required Description
product Product (full) Yes Product

Notes

This method requires the patternstore-write permission.

projects

projects/comments

GET /projects/{username}/{id}/comments.json
Retrieve a project's comments

Parameters

Name Type Required Description
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Defaults to 25 comments per page. Maximum is 100.
sort String Sort order. Options are: time (and time_ for a descending sort)

Return Values

Name Type Required Description
comments Array, Comment Yes Comments with nested replies.
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Comments have one level of nesting. Replies from the owner of the project may be nested under the "replies" attribute.

projects/crafts authenticated

POST /projects/crafts.json
Get list of crafts that are valid for use within projects

Return Values

Name Type Required Description
crafts Array, Craft (list) Yes List of crafts

projects/create authenticated

POST /projects/{username}/create.json
Create project

URI Parameters

Name Type Required Description
username String Yes User to create a project for

Parameters

Name Type Required Description
data Project (POST) Yes Project JSON object

Return Values

Name Type Required Description
project Project (full) Yes Project

Notes

Packs can be added to a project only on creation. A pack is an allocation of yarn. If associated with a stash entry, you only need to (optionally) supply the "total_weight" and "total_length" attributes. The rest are inherited. To update or delete a pack, use the pack API methods.

projects/create_photo authenticated

POST /projects/{username}/{id}/create_photo.json
Add a photo to a project (using an uploaded image or URL as a source)

URI Parameters

Name Type Required Description
username String Yes Username of the user who owns the project
id Integer Yes Project ID

Parameters

Name Type Required Description
image_id Integer Uploaded image to use, created via /upload/image.json
source_url String URL of the image to use (preferably high-res)

Return Values

Name Type Required Description
status_token String Yes Token that can be used to check the status of the photo

Notes

This method will create a new photo using one of two sources:

  • If image_id is supplied, the photo will be created from an image that was uploaded via /upload/image.json
  • If source_url is supplied, the source image will be retrieved from a URL

This method returns immediately. The image will be added to the project as a photo once it has been processed and resized into the various sizes used by Ravelry. Any size image is accepted. Ravelry will store the original or a 1600x1600 version (whichever is smaller) in addition to all of the necessary thumbnails.

Photo creation time varies depending on the size of the image. It should complete within a few seconds. If you'd like to monitor the status of the process, you can use the status_token that is returned with /photos/status.json

projects/delete authenticated

DELETE /projects/{username}/{id}.json
Permanently delete a project

URI Parameters

Name Type Required Description
username String Yes User who owns the project
id Integer Yes Project ID

Return Values

Name Type Required Description
project Project (full) Yes Project that was deleted

projects/list authenticated

GET /projects/{username}/list.json
Get project list

URI Parameters

Name Type Required Description
username String Yes User to retrieve projects from

Parameters

Name Type Required Description
sort String Sort order. Accepted options: status, name, created, started, favorites, happiness. Multiple space-delimited options are accepted.
include Array, String Extra result parts to include. Accepted options: collections
page Integer Result page to retrieve. Defaults to 1 (the first page).
page_size Integer Defaults to null (the entire result set in 1 page)

Return Values

Name Type Required Description
collections Array, Collection Project sets
projects Array, Project (small) Yes All projects
paginator Paginator Yes Pagination object with total results, pages

Example

/projects/cassidy/list.json?include=collections

projects/project_statuses authenticated

POST /projects/project_statuses.json
Get list of statuses that are valid for use within projects

Return Values

Name Type Required Description
project_statuses Array, ProjectStatus (list) Yes List of project statuses

projects/reorder_photos authenticated

POST /projects/{username}/{id}/reorder_photos.json
Change order of associated photos

URI Parameters

Name Type Required Description
username String Yes User who owns the project
id Integer Yes Project ID

Parameters

Name Type Required Description
sort_order String Yes List of photo IDs, space delimited

Return Values

Name Type Required Description
photos Array, Photo (full) Yes Set of project photos with updated ordering

Notes

The first photo becomes the primary photo for the project
GET /projects/search.json
Search the project database

Parameters

Name Type Required Description
query String Search term for fulltext searching
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Defaults to 50 results per page.
sort String Sort order. Options are: best, started, completed, favorites, helpful, updated, happiness
include Array, String Extra result parts to include. Space delimited. Accepted options: notes, packs (see Pack)
personal_attributes Boolean set to 1 if you would like to return the personal_attributes hash in the result objects

Return Values

Name Type Required Description
projects Array, Project Yes Matching projects
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Note that you may also use any of the (many) parameters for filters that are available in the on-site project search. For example, searching for the tags "red OR blue" would be tag-list=red|blue. Searching for the tags red AND blue would be tag-list=red blue

Example

/projects/search.json?query=dalek

projects/show authenticated

GET /projects/{username}/{id}.json
Get project detail

URI Parameters

Name Type Required Description
username String Yes User to retrieve projects from
id Integer Yes Project ID or permalink

Parameters

Name Type Required Description
include Array, String Extra result parts to include. Accepted options: comments

Return Values

Name Type Required Description
project Project (full) Yes Project
comments Array, Comment Comments

Example

/projects/shadiradio/1.json?include=comments

projects/update authenticated

POST /projects/{username}/{id}.json
Update project

URI Parameters

Name Type Required Description
username String Yes User to update a project for
id Integer Yes Project ID

Parameters

Name Type Required Description
data Project (POST) Yes Project JSON object

Return Values

Name Type Required Description
project Project (full) Yes Project

Notes

Packs can be added to a project only on creation. A pack is an allocation of yarn. If associated with a stash entry, you only need to (optionally) supply the "total_weight" and "total_length" attributes. The rest are inherited. To update or delete a pack, use the pack API methods.

queue

queue/create authenticated

POST /people/{username}/queue/create.json
Create a queued project

URI Parameters

Name Type Required Description
username String Yes User who owns the queued project

Parameters

Name Type Required Description
data QueuedProject (POST) Yes Queued project JSON object

Return Values

Name Type Required Description
queued_project QueuedProject (full_for_owner) Yes The newly created queued project

Notes

A typical *minimal* queue entry would consist of a pattern_id (to link to a pattern in Ravelry) and a sort_order (to position the item within the users' queue)

Example

/people/username/queue/create.json {"pattern_id": 42, "sort_order": 2 }

queue/delete authenticated

DELETE /people/{username}/queue/{queued_project_id}.json
Delete a queued project

URI Parameters

Name Type Required Description
queued_project_id Integer Yes Queued project to delete

Return Values

Name Type Required Description
queued_project QueuedProject (full) Yes Queued project that was deleted

queue/list authenticated

GET /people/{username}/queue/list.json
Get queued project list

URI Parameters

Name Type Required Description
username String Yes User to retrieve queued projects from

Parameters

Name Type Required Description
pattern_id Integer Pattern ID to filter for
query String Full text search query
query_type String One of "patterns" (to search pattern full text) or "tags" to search tags in queued items. Default is 'patterns'
page Integer Yes Result page to retrieve. Defaults to 1 (the first page).
page_size Integer Yes Defaults to 50 results per page.

Return Values

Name Type Required Description
queued_projects Array, QueuedProject (small) Yes All queued projects
paginator Paginator Yes Pagination object with total results, pages, etc

Example

/people/username/queue/list.json

queue/order authenticated

GET /people/{username}/queue/order.json
Get queue ordering (list of all names, ids, and positions)

URI Parameters

Name Type Required Description
username String Yes User to retrieve queued projects from

Return Values

Name Type Required Description
queued_projects Array, QueuedProject (tiny) Yes All queued projects

Example

/people/username/queue/order.json

queue/reposition authenticated

POST /people/{username}/queue/{id}/reposition.json
Move a queued project to a new position

URI Parameters

Name Type Required Description
username String Yes User who owns the queued project
id Integer Yes ID of the queued project

Parameters

Name Type Required Description
insert_at Integer Yes New position for the queued project, range from 1 - (number of items in queue)

Return Values

Name Type Required Description
queued_project QueuedProject (tiny) Yes The updated queued project

Example

/people/username/queue/1/reposition.json

queue/show authenticated

GET /people/{username}/queue/{id}.json
Get queued project detail

URI Parameters

Name Type Required Description
username String Yes User to retrieve queued project from
id String Yes Queued project ID

Return Values

Name Type Required Description
queued_project QueuedProject (full) Yes Queued project

Example

/people/username/queue/1.json

queue/update authenticated

POST /people/{username}/queue/{id}/update.json
Update a queued projectn

URI Parameters

Name Type Required Description
username String Yes User who owns the queued project

Parameters

Name Type Required Description
data QueuedProject (POST) Yes Queued project JSON object. Attributes that are not being changed can be omitted.

Return Values

Name Type Required Description
queued_project QueuedProject (full_for_owner) Yes The newly updated queued project

Example

/people/username/queue/1/update.json {"notes": "Blah blah"}

saved_searches

saved_searches/list

GET /saved_searches/list.json
Get list of saved searches for the current user

Return Values

Name Type Required Description
saved_searches Array, SavedSearch (list) Yes

shops

GET /shops/search.json
Search yarn shop database

Parameters

Name Type Required Description
query String search query for full text search
shop_type_id Integer restrict shop type, 1 = Local Yarn Store
lat Float latitude for geographical search
lng Float longitude for geographical search
radius Integer radius for geographical search
units String units for geo search, "miles" or "km"
page Integer result page to retrieve. Defaults to 1 (the first page).
page_size Integer number of results per page. Defaults to 100

Return Values

Name Type Required Description
shops Array, Shop (small) Yes
paginator Paginator Yes Pagination object with total results, pages

Notes

All parameters are optional. Set shop_type_id to 1 to filter out online stores and chains/craft stores such as Wal-Mart, Michael's When using geographical search (search radius around a point), lat, lon, radius, and units are all required parameters. Geo search can also be combined with a search term.

Example

/shops/search.json?lat=42.35892&lng=-71.05781&radius=100&query=yarn

shops/show

GET /shops/{id}.json
Get shop details

URI Parameters

Name Type Required Description
id Integer Yes Shop to retrieve

Parameters

Name Type Required Description
include Array, String Extra result parts to include. Accepted options: brands, ad, schedules, photo

Return Values

Name Type Required Description
shop Shop (medium) Yes
brands Array, Brand Yes Brands purchased at the store (verified => false and yarns array empty) and advertised by the store (verified => true and yarns array filled)
ad Ad (shop) Yes
schedules Array, ShopSchedule (shop) Yes
photo Photo (small) Yes

Example

/shops/2588.json?include=brands+ad

stash

stash/comments

GET /people/{username}/stash/{id}/comments.json
Retrieve a stashed yarn's comments

Parameters

Name Type Required Description
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Defaults to 25 comments per page. Maximum is 100.
sort String Sort order. Options are: time (and time_ for a descending sort)

Return Values

Name Type Required Description
comments Array, Comment Yes Comments with nested replies.
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Comments have one level of nesting. Replies from the owner of the stashed yarn may be nested under the "replies" attribute.

stash/create authenticated

POST /people/{username}/stash/create.json
Create stash record

URI Parameters

Name Type Required Description
username String Yes User to create stash for

Parameters

Name Type Required Description
data Stash (POST) Yes Stash JSON object

Return Values

Name Type Required Description
stash Stash (full) Yes Stash

Example

/people/username/stash/create.json { "yarn_id": 1, "dye_lot": 42 }

stash/create_photo authenticated

POST /people/{username}/stash/{id}/create_photo.json
Add a photo to a stashed yarn (using an uploaded image or URL as a source)

URI Parameters

Name Type Required Description
username String Yes Username of the user who owns the stash entry
id String Yes Stash ID

Parameters

Name Type Required Description
image_id Integer Uploaded image to use, created via /upload/image.json
source_url String URL of the image to use (preferably high-res)

Return Values

Name Type Required Description
status_token String Yes Token that can be used to check the status of the photo

Notes

See the projects/create_photo documentation for more information on how this works.

stash/delete authenticated

DELETE /people/{username}/stash/{id}.json
Permanently delete a stash entry

URI Parameters

Name Type Required Description
username String Yes User who owns the stash entry
id Integer Yes Stash ID

Return Values

Name Type Required Description
stash Stash (full) Yes Stash that was deleted

stash/list authenticated

GET /people/{username}/stash/list.json
Get stash list

URI Parameters

Name Type Required Description
username String Yes User to retrieve stash from

Parameters

Name Type Required Description
page Integer If paging is desired, result page to retrieve. Defaults to 1 (the first page).
page_size Integer If paging is desired, number of results per page. Defaults to 50 results per page.
sort String Sort order. Should be one of: recent, alpha, weight, colorfamily, yards. Defaults to "alpha".

Return Values

Name Type Required Description
stash Array, Stash (small) Yes All stash

Example

/people/username/stash/list.json

stash/reorder_photos authenticated

POST /people/{username}/stash/{id}/reorder_photos.json
Change order of associated photos

URI Parameters

Name Type Required Description
username String Yes User who owns the stash entry
id Integer Yes Stash ID

Parameters

Name Type Required Description
sort_order String Yes List of photo IDs, space delimited

Return Values

Name Type Required Description
photos Array, Photo (full) Yes Set of project photos with updated ordering

Notes

The first photo becomes the primary photo for the project
GET /stash/search.json
Search the project database

Parameters

Name Type Required Description
query String Search term for fulltext searching
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Defaults to 50 results per page.
sort String Sort order. Options are: best, added, favorites
include Array, String Extra result parts to include. Space delimited. Accepted options: notes

Return Values

Name Type Required Description
stashes Array, Stash Yes Matching stashed yarns
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Note that you may also use any of the (many) parameters for filters that are available in the on-site stash search.

Example

/stash/search.json?query=wollmeise

stash/show authenticated

GET /people/{username}/stash/{id}.json
Get stash list

URI Parameters

Name Type Required Description
username String Yes User to retrieve stash from
id Integer Yes Stash ID or permalink

Return Values

Name Type Required Description
stash Stash (full) Yes Stash
user User (small) Yes User

Example

/people/username/stash/96647.json

stash/unified/list authenticated

GET /people/{username}/stash/unified/list.json
Get unified stash list that combines yarn stash with fiber stash

URI Parameters

Name Type Required Description
username String Yes User to retrieve stash from

Parameters

Name Type Required Description
page Integer If paging is desired, result page to retrieve. Defaults to 1 (the first page).
page_size Integer If paging is desired, number of results per page. Defaults to 50 results per page.
sort String Sort by should be one of: recent, alpha, weight, colorfamily, grams. Defaults to "alpha".

Return Values

Name Type Required Description
unified_stash Array, UnifiedStash (list) Yes List of unified stash records, either {stash: [Stash#list object]} or {fiber_stash: [FiberStash#list object]}

Example

/people/username/stash/list.json

stash/update authenticated

POST /people/{username}/stash/{id}.json
Update a stash record

URI Parameters

Name Type Required Description
username String Yes User who owns stash
id Integer Yes Stash record to update

Parameters

Name Type Required Description
data Stash (POST) Yes Stash JSON object

Return Values

Name Type Required Description
stash Stash (full) Yes Stash

Example

/people/username/stash/96647.json { "location": "Under the bed" }

stores

stores/list

GET /stores/list.json
List the current user's pattern stores

Return Values

Name Type Required Description
stores Array, Store (list) Yes List of pattern stores that the current user administers

Required permissions

patternstore-read OR patternstore-write

Notes

This method requires patternstore-read permissions.

stores/products

GET /stores/#{store_id}/products.json
List the products in a user's stores

Parameters

Name Type Required Description
store_id Integer Yes Pattern store to query
page Integer Result page to retrieve. Defaults to 1 (the first page).
page_size Integer Defaults to null (the entire result set in 1 page)

Return Values

Name Type Required Description
products Array, Product (list) Yes List of active products in the selected store

Required permissions

patternstore-read OR patternstore-write

Notes

This method requires patternstore-read permissions.

stores/purchases

GET /stores/:id/purchases.json
Export purchase (transaction) history

Parameters

Name Type Required Description
store_id Integer Yes Pattern store to query
creator String One of "all", ravelry-purchase", "lys-sale", or "lys-payment"
min_paid_date Date Minimum paid date stamp as RFC 3339 timestamp with offset: YYYY-MM-DDTHH:mm:ss±HH:MM
sort String Sort order. Options are: date, paid_date (and date_, paid_date_ for a descending sort)
month String Export mode: if a month is supplied, all invoices for that month will be returned with no pagination. The month that you want to retrieve in YYYY-MM-DD format (day will always be "01")
page Integer Result page to retrieve. Defaults to 1 (the first page).
page_size Integer Defaults to 100. Maximum size accepted = 250

Return Values

Name Type Required Description
invoices Array, Invoice (sale) Yes List of invoices that match the criteria
paginator Paginator Pagination object with total results, pages. Not returned if month parameter is supplied (export mode).

Required permissions

patternstore-purchases

Notes

This method requires patternstore-purchases permissions. The patternstore-purchases scope is not available to OAuth apps/keys

Explanation of creator options:

  • all = exports every transaction
  • ravelry-purchase = Ravelry sales only, LYS payments and sales are omitted
  • lys-sale = LYS sales (from an LYS to the LYS customer)
  • lys-payment = LYS payment (payments from an LYS to designer, for previously sold patterns)

topics

topics/create

POST /topics/create.json
Create a new topic

URI Parameters

Name Type Required Description
forum_id Integer Yes Forum that should contain the created topic

Parameters

Name Type Required Description
title String Yes Title of this topic. 250 character limit.
tag_list String List of tags, space delimited
body String Content for the (first) forum post that will kick off this topic
summary String Summary of this topic. Can only be set by a moderator.
sticky Boolean Sticky status, show at top of board. Defaults to false. Can only be set by a moderator.
locked Boolean Locked status, new posts can not be added. Defaults to false. Can only be set by a moderator.
archived Boolean Archived. Post appears in "archive" section of forum. Can only be set by a moderator.

Return Values

Name Type Required Description
topic Topic (full) Yes Newly created topic
forum_post ForumPost (full) Yes Newly created forum post, the first post in the topic

Required permissions

forum-write

Notes

This method requires forum-write permissions.

topics/posts authenticated

GET /topics/{topic_id}/posts.json
Get post list for a specific forum, personalize for the authenticated user

URI Parameters

Name Type Required Description
topic_id Integer Yes Topic to retrieve posts from

Parameters

Name Type Required Description
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Page size. Defaults to 25.
sort_reverse Boolean Default sort is oldest posts first. Set to 1 to reverse sort order.
include Array, String Extra result parts to include. Space delimited. Accepted options: vote_totals, user_votes

Return Values

Name Type Required Description
posts Array, ForumPost (list) Yes List of posts
paginator Paginator Yes Pagination object with total results, pages, etc
vote_totals ForumMarkers vote_totals are returned if they are requested with the "include" parameter
user_votes Array, String user_votes are returned if they are requested with the "include" parameter

Example

/topics/848/posts.json

topics/read authenticated

POST /topics/{topic_id}/read.json
Update read/unread marker for a specific topic

URI Parameters

Name Type Required Description
topic_id Integer Yes Topic to update

Parameters

Name Type Required Description
last_read Integer Yes Last read post number
force optional Yes 1 = Force setting last read, even if has decreased

Return Values

Name Type Required Description
topic_status TopicStatus Yes Topic status - last read/latest reply/etc

Notes

Note the "force" parameter - setting to 1 forces an update. By default, the last read marker will only be updated if it is earlier than the post number that you are trying to set. The number can be forced to an earlier number (normally 0) if the user wishes to clear their read marker or reset the number.

Example

/topics/1/read.json?last_read=1

topics/reply

POST /topics/{topic_id}/reply.json
Post a reply to a topic

URI Parameters

Name Type Required Description
topic_id Integer Yes Topic to reply to

Parameters

Name Type Required Description
body String Yes Forum post content
parent_post_id Integer If replying to a specific post, ID of post being replied to

Return Values

Name Type Required Description
forum_post ForumPost (full) Yes Newly created forum post

Required permissions

forum-write

Notes

This method requires forum-write permissions.

topics/show authenticated

GET /topics/{topic_id}.json
Get topic information

URI Parameters

Name Type Required Description
topic_id Integer Yes Topic to retrieve

Return Values

Name Type Required Description
topic Topic (full) Yes Topic

Example

/topics/848.json

topics/update

POST /topics/{id}.json
Update a topic

URI Parameters

Name Type Required Description
id Integer Yes Topic to update

Parameters

Name Type Required Description
title String Yes Title of this topic. 250 character limit.
tag_list String List of tags, space delimited
summary String Summary of this topic. Can only be set by a moderator.
sticky Boolean Sticky status, show at top of board. Defaults to false. Can only be set by a moderator.
locked Boolean Locked status, new posts can not be added. Defaults to false. Can only be set by a moderator.
archived Boolean Archived. Post appears in "archive" section of forum. Can only be set by a moderator.

Return Values

Name Type Required Description
topic Topic (full) Yes Newly updated topic

Required permissions

forum-write

Notes

Note that regular (non-moderator) users can only update information for an existing topic during the grace period (5 minutes after it has been created). The first forum post that started the topic can be updated independently using the forum posts API. This method requires forum-write permissions.

upload

upload/image

POST /upload/image.json
Upload an image file for later processing or attaching

Parameters

Name Type Required Description
upload_token String Yes Upload token received from upload/request_token
file0 Multipart Yes File data
file1 Multipart File data, second file
file2 Multipart File data, third file...
file9 Multipart File data, tenth file

Return Values

Name Type Required Description
uploads Object Yes Object with result for each uploaded file. See notes.

Notes

Supported image formats: PNG, JPEG and HEIF/HEIC.

Note that this method is NOT authenticated. OAuth headers or other signatures are not needed. You must supply an upload_token that you received from a separate /upload/request_token.json API request. The upload token can only be used once.

This should be a multipart POST and up to 10 files can be included. This method will return immediately once your POST has completed.

The size of a single POST cannot exceed 50 MB. If you try to POST more than 50 MB of data you will receive HTTP Error 413: Request entity too large

The result will include keys for each file parameter that you supplied, and each will contain an object with an "image_id". This "image_id" can be used when adding photos to projects, stash, etc.

Example response:
{uploads: [{file0: {image_id: 16}}, {file1: {image_id: 17}}, {file2: {image_id: 18}}]}

upload/request_token

POST /upload/request_token.json
Generate an upload token

Return Values

Name Type Required Description
upload_token String Yes

Notes

In order to upload files, you must first request an upload token that will be included when you POST your file data.

Example

/upload/request_token.json

upload/status

GET /upload/image/status.json
Get uploaded image IDs

Parameters

Name Type Required Description
upload_token String Yes Upload token received from upload/request_token

Return Values

Name Type Required Description
uploads Object Yes Object with result for each uploaded file. See notes.

Notes

This method might be useful if you POST to /upload/image.json with code that does not communicate with your client code.

See POST /upload/image.json for an example response.

volumes

volumes/apply_updates authenticated

POST /volumes/{id}/apply_updates.json
Apply any unapplied updates to a volume and any related volumes (in the case of a product with multiple PDF documents attached)

URI Parameters

Name Type Required Description
id Integer Yes Volume ID to apply updates to

Return Values

Name Type Required Description
success Boolean Yes returns true if updates were applied successfully
added_volumes Array, Volume (full) Yes Any newly added volumes (documents)
removed_volumes Array, Volume (full) Yes Any removed volumes (replaced or removed documents)

volumes/create authenticated

POST /volumes/create.json
Create a new volume (library entry) in the current user's library

Parameters

Name Type Required Description
data Volume (POST) Yes Volume JSON object. Note that pattern_id or pattern_source_id is required.

Return Values

Name Type Required Description
volume Volume (full) Yes Volume

Notes

If a free pattern that is available on Ravelry is added to the library, the associated PDFs will be included automatically.

Users should be encouraged to use the library for recording items that they own (and not for some other purpose) All patterns and sources can be added to the library, but adding single non-free patterns to the library without purchasing should be relatively rare.

Adding arbitrary items to the library is not yet supported. You can add by pattern ID or pattern source ID. If you have as ISBN, you can use the pattern source search to look a matching source or sources.

volumes/delete authenticated

DELETE /volumes/{id}.json
Delete a volume

URI Parameters

Name Type Required Description
username String Yes User who owns the volume
id Integer Yes Id of the volume that should be deleted

Return Values

Name Type Required Description
volume Volume (full) Yes The deleted record

volumes/show authenticated

GET /volumes/{id}.json
Get volume details

URI Parameters

Name Type Required Description
id Integer Yes Volume ID to retrieve

Return Values

Name Type Required Description
volume Volume (full) Yes Volume object

Example

/volumes/42.json

volumes/update authenticated

POST /volumes/{id}/update.json
Create a new volume (library entry)

URI Parameters

Name Type Required Description
id Integer Yes ID of the volume to update

Parameters

Name Type Required Description
data Volume (POST) Yes Volume JSON object.

Return Values

Name Type Required Description
volume Volume (full) Yes Volume

Notes

The pattern or pattern source of a volume cannot be changed after creation.

yarn_attributes

yarn_attributes/list

GET /yarn_attributes/groups.json
List the current pattern attributes

Return Values

Name Type Required Description
yarn_attribute_groups Array, YarnAttributeGroup (list) Yes List of all current yarn attributes, organized into groups that contain attributes and possibly sub-groups

Notes

Yarn attributes seldom change, I'd recommend caching them for up to 24 hours. This method does not require an API key.

yarn_companies

GET /yarn_companies/search.json
Search the yarn company directory

Parameters

Name Type Required Description
query String Search term for fulltext searching
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Defaults to 48 results per page.
sort String Sort order. Options are: "best" (defaults to "best")

Return Values

Name Type Required Description
yarn_companies Array, YarnCompany (list) Yes Matching yarn companies
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Note that you may also use any of the parameters for filters that are available in the on-site yarn brand search.

Example

/yarn_companies/search.json?query=wollmeise

yarns

yarns/comments

GET /yarns/{id}/comments.json
Retrieve a yarns's comments

Parameters

Name Type Required Description
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Defaults to 25 comments per page. Maximum is 100.
sort String Sort order. Options are: time, helpful (and time_, helpful_ for a descending sort)
include Array, String Extra result parts to include. Space delimited. Accepted options: highlighted_project

Return Values

Name Type Required Description
comments Array, Comment Yes Comments with nested replies.
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Comments have one level of nesting. Replies from the owner of the yarn may be nested under the "replies" attribute.
GET /yarns/search.json
Search yarn database

Parameters

Name Type Required Description
query String Search term for fulltext searching yarns
page Integer Result page to retrieve. Defaults to first page.
page_size Integer Defaults to 50 results per page.
sort String Sort order. Options are: best, rating, projects
personal_attributes Boolean set to 1 if you would like to return the personal_attributes hash in the result objects

Return Values

Name Type Required Description
yarns Array, Yarn (list) Yes Matching yarns
paginator Paginator Yes Pagination object with total results, pages, etc

Notes

Note that you may also use any of the (many) parameters for filters that are available in the on-site yarn search.

Example

/yarns/search.json?query=cascade

yarns/show

GET /yarns/{id}.json
Get yarn details

URI Parameters

Name Type Required Description
id Integer Yes Yarn to retrieve

Parameters

Name Type Required Description
include Array, String Extra result parts to include. Space delimited. Accepted options: colorways, availability

Return Values

Name Type Required Description
yarn Yarn (full) Yes
colorways Array, Colorway (full)
availability Array, YarnCountry (full) Note that yarn availability-by-country data is not a user-maintained part of the database. The returned records provide advertiser and recent project/stash "purchased at" data.

Example

/yarns/573.json

yarns/yarns

GET /yarns.json
Get yarn details for multiple yarns

Parameters

Name Type Required Description
ids Integer Yes Space delimited list of yarn IDs to retrieve

Return Values

Name Type Required Description
yarns Object Yes Map of `Yarn#full` results, indexed by yarn ID

Example

/yarns.json?ids=600+601

Business

Business

Attributes

Name Type Nullable Description
id
name
permalink
primary_url

Business (list)

Attributes

Name Type Nullable Description
id
name
permalink
primary_url

FiberPack

FiberPack (full)

Attributes

Name Type Nullable Description
id Integer

FiberPack (POST)

Attributes

Name Type Nullable Description
color_family_id Integer Yes
colorway String Yes
fiber_stash_id Integer
personal_brand String Yes
personal_name String Yes
purchased_at String Yes
purchased_city String Yes
purchased_country_id Integer Yes
purchased_state_id
purchased_url String Yes
shop_id Integer Yes
spinning_project_id String

NeedleSize

NeedleSize (list)

Attributes

Name Type Nullable Description
hook String Crochet hook designation corresponding to this metric size, if one exists
id Integer Needle size ID
metric Integer Metric designation for hook size
name
pretty_metric
us String US size number corresponding to this metric size, if one exists

NeedleSize (full)

Attributes

Name Type Nullable Description
hook String Crochet hook designation corresponding to this metric size, if one exists
id Integer Needle size ID
metric Integer Metric designation for hook size
name
pretty_metric
us String US size number corresponding to this metric size, if one exists

NeedleSize (POST)

Attributes

Name Type Nullable Description
metric Integer Metric designation for hook size

YarnWeight

YarnWeight

Attributes

Name Type Nullable Description
crochet_gauge
id
knit_gauge
max_gauge
min_gauge
name
ply
wpi

YarnWeight (list)

Attributes

Name Type Nullable Description
crochet_gauge
id
knit_gauge
max_gauge
min_gauge
name
ply
wpi

PatternNeedleSize

PatternNeedleSize (list)

Attributes

Name Type Nullable Description
hook
id
metric
needle_name
needle_size_id
pretty_metric
pretty_us
us

PatternNeedleSize (POST)

Attributes

Name Type Nullable Description
hook
id
needle_size_id

Language

Language

Attributes

Name Type Nullable Description
code String 2 character Language code (ISO 639-1)
id Integer Language ID
name String Language name
permalink String Permalink
short_name String Short language name
universal Boolean True if this is the "Universal" (no written language) language

Language (list)

Attributes

Name Type Nullable Description
code String 2 character Language code (ISO 639-1)
id Integer Language ID
name String Language name
permalink String Permalink
short_name String Short language name
universal Boolean True if this is the "Universal" (no written language) language

DraftPatternYarn

DraftPatternYarn (full)

Attributes

Name Type Nullable Description
created_at Date
draft_pattern_id Integer draft pattern id
id Integer
updated_at Date
yarn Yarn (list) Yarn
yarn_id Integer yarn id
yarn_name
yarn_weight YarnWeight (list) Yarn weight

DraftPatternYarn (POST)

Attributes

Name Type Nullable Description
id Integer
yarn_id Integer yarn id

QueuedProject

QueuedProject (tiny)

Attributes

Name Type Nullable Description
id Integer
position_in_queue Integer
short_pattern_name String

QueuedProject (small)

Attributes

Name Type Nullable Description
best_photo Photo
created_at Date
id Integer
name String
notes
pattern_author_id
pattern_author_name
pattern_id String Yes ID of pattern to be used for this project
pattern_name String
position_in_queue Integer
short_pattern_name String
skeins Integer Yes # of skeins needed
sort_order Integer Yes Position in queue. Defaults to last.
user_id Integer
yarn_id String Yes ID of yarn to be used in this project
yarn_name String

QueuedProject (full)

Attributes

Name Type Nullable Description
best_photo Photo
created_at Date
id Integer
name String
notes_html String
notes
pattern Pattern (full)
pattern_id String Yes ID of pattern to be used for this project
pattern_name String
position_in_queue Integer
queued_stashes Array, Stash (full)
skeins Integer Yes # of skeins needed
sort_order Integer Yes Position in queue. Defaults to last.
user_id Integer
yarn Yarn (full)
yarn_id String Yes ID of yarn to be used in this project
yarn_name String

QueuedProject (small_for_owner)

Attributes

Name Type Nullable Description
best_photo Photo
created_at Date
finish_by
id Integer
make_for String Yes Note about who the project is for. Limited to 128 characters.
name String
notes
pattern_author_id
pattern_author_name
pattern_id String Yes ID of pattern to be used for this project
pattern_name String
position_in_queue Integer
short_pattern_name String
skeins Integer Yes # of skeins needed
sort_order Integer Yes Position in queue. Defaults to last.
start_on Date Yes Date to start the project date, in YYYY-MM-DD format.
user_id Integer
yarn_id String Yes ID of yarn to be used in this project
yarn_name String

QueuedProject (full_for_owner)

Attributes

Name Type Nullable Description
best_photo Photo
created_at Date
finish_by
id Integer
make_for String Yes Note about who the project is for. Limited to 128 characters.
name String
notes_html String
notes
pattern Pattern (full)
pattern_id String Yes ID of pattern to be used for this project
pattern_name String
position_in_queue Integer
queued_stashes Array, Stash (full)
skeins Integer Yes # of skeins needed
sort_order Integer Yes Position in queue. Defaults to last.
start_on Date Yes Date to start the project date, in YYYY-MM-DD format.
user_id Integer
yarn Yarn (full)
yarn_id String Yes ID of yarn to be used in this project
yarn_name String

QueuedProject (export)

Attributes

Name Type Nullable Description
best_photo Photo
created_at Date
finish_by
id Integer
make_for String Yes Note about who the project is for. Limited to 128 characters.
name String
notes_html String
notes
pattern Pattern (full)
pattern_id String Yes ID of pattern to be used for this project
pattern_name String
position_in_queue Integer
queued_stashes Array, Stash (full)
skeins Integer Yes # of skeins needed
sort_order Integer Yes Position in queue. Defaults to last.
start_on Date Yes Date to start the project date, in YYYY-MM-DD format.
user_id Integer
yarn Yarn (full)
yarn_id String Yes ID of yarn to be used in this project
yarn_name String

QueuedProject (POST)

Attributes

Name Type Nullable Description
fiber_stash_ids Array, Integer Yes List of IDs for Fiber stash records that are associated with this queued item.
finish_by Date Yes Date to finish the project by, in YYYY-MM-DD format.
make_for String Yes Note about who the project is for. Limited to 128 characters.
notes String
pattern_id String Yes ID of pattern to be used for this project
personal_pattern_author String Yes Pattern author, if a Ravelry pattern is not linked
personal_pattern_name String Yes Pattern name, if a Ravelry pattern is not linked
personal_pattern_url String Yes Pattern URL, if a Ravelry pattern is not linked
personal_yarn_name String Yes Yarn name, if a Ravelry yarn is not linked
skeins Integer Yes # of skeins needed
sort_order Integer Yes Position in queue. Defaults to last.
sort_order Integer Yes Position in queue. Defaults to last.
start_on Date Yes Date to start the project date, in YYYY-MM-DD format.
stash_ids Array, Integer Yes List of IDs for Stash records that are associated with this queued item.
tag_names Array, String Yes Array of tag names
yarn_id String Yes ID of yarn to be used in this project

PatternSource

PatternSource

Attributes

Name Type Nullable Description
amazon_rating Float Yes
amazon_url String Yes
author String Yes
id Integer
list_price Decimal Yes
name String
out_of_print Boolean
patterns_count Integer
permalink String
price Decimal Yes
shelf_image_path String Yes
url

Attributes

Name Type Nullable Description
id Integer
name String
pattern_source_type
patterns Array, Pattern (link)
permalink String

PatternSource (list)

Attributes

Name Type Nullable Description
amazon_rating Float Yes
amazon_url String Yes
author String Yes
id Integer
list_price Decimal Yes
name String
out_of_print Boolean
pattern_source_type
pattern_source_type_id
patterns_count Integer
permalink String
price Decimal Yes
shelf_image_path String Yes
url

PatternSource (public)

Attributes

Name Type Nullable Description
author String Yes
author_pattern_author_id
created_at
id Integer
isbn_13
issue
label
name String
notes_html
notes
out_of_print Boolean
pattern_source_type
pattern_source_type_id
periodical
permalink String
price Decimal Yes
publication_date
publisher_id
source_group_id
updated_at
url

PatternSource (full)

Attributes

Name Type Nullable Description
amazon_rating Float Yes
amazon_url String Yes
author String Yes
id Integer
list_price Decimal Yes
name String
out_of_print Boolean
pattern_source_type
patterns Array, Pattern
patterns_count Integer
permalink String
price Decimal Yes
shelf_image_path String Yes
url

DraftNeedleSize

DraftNeedleSize (full)

Attributes

Name Type Nullable Description
draft_pattern_id Integer
hook Boolean Tool is a crochet hook (as opposed to a needle)
id Integer
needle_size Array, NeedleSize (list) Length, name, etc attributes come from the associated needle size record

DraftNeedleSize (POST)

Attributes

Name Type Nullable Description
hook Boolean Tool is a crochet hook (as opposed to a needle)
id Integer
needle_size_id Integer

Invoice

Invoice (cart)

Attributes

Name Type Nullable Description
id
invoice_number Integer Invoice number
paid Boolean paid or unpaid
payment_reference String Yes Custom field for storage of reference data by API users

Invoice (receipt)

Attributes

Name Type Nullable Description
id
invoice_number Integer Invoice number
paid Boolean paid or unpaid
payment_reference String Yes Custom field for storage of reference data by API users

Invoice (sale)

Attributes

Name Type Nullable Description
amount_due Decimal Yes Amount due to the seller
amount_due_to_lys Decimal Yes Amount due to the LYS (for In Store Sales)
bill_to_email String Yes The email of the payer, as reported by PayPal
bill_to_name String Yes The name of the payer, as reported by PayPal
country String Yes Country of the buyer for tax purposes. Typically the same as country_from_paypal.
country_from_paypal String Yes Country of the buyer as reported by PayPal
creator_type Integer Yes Flag to mark special kinds of invoice records. 1 = (reserved), 2 = free/gifted copy, 3 = record of transaction between LYS and customer
currency String Currency (3 letter ISO code)
id
invoice_date Date Date the invoice was created
invoice_line_items Array, InvoiceLineItem (sale) Products purchased and promotions applied
invoice_number Integer Invoice number
paid Boolean paid or unpaid
payment_reference String Yes Custom field for storage of reference data by API users
payments Array, Payment Associated payments (from PayPal)
ravelry_user_id Integer Yes User ID of the buyer's Ravelry account, ONLY PRESENT if the buyer was logged in to Ravelry at the time of purchase
ravelry_username String Yes Username of the buyer's Ravelry account, ONLY PRESENT if the buyer was logged in to Ravelry at the time of purchase

Invoice

Attributes

Name Type Nullable Description
bill_to_email String Yes The email of the payer, as reported by PayPal
bill_to_name String Yes The name of the payer, as reported by PayPal
currency String Currency (3 letter ISO code)
id
invoice_date Date Date the invoice was created
invoice_number Integer Invoice number
paid Boolean paid or unpaid

Document

Document

Attributes

Name Type Nullable Description
bytes Integer Size of the file in bytes
content_type String MIME content type of the file
filename String File name
id Integer Document ID
notes String Yes Seller-added notes about the content of the file
thumbnail_url String URL for a thumbnail image of the attachment or the first page of the attachment

YarnProvenance

YarnProvenance

Attributes

Name Type Nullable Description
country_id
country_name
description
id Integer identifier
phase_name
state_id
yarn_id Integer yarn identifier
yarn_phase_id Integer yarn phase identifier

YarnProvenance (full)

Attributes

Name Type Nullable Description
country_id
country_name
description
id Integer identifier
phase_name
state_id
yarn_id Integer yarn identifier
yarn_phase_id Integer yarn phase identifier

Delivery

Delivery (list)

Attributes

Name Type Nullable Description
created_at Date
emailed_at Date
id Integer Delivery ID
products Array, Product Products that were purchased or gifted

Delivery (receipt)

Attributes

Name Type Nullable Description
delivery_url String URL where the customer can pick their downloads
emailed_at Date
id Integer Delivery ID
product_attachments Array, ProductAttachment (receipt) Details about the file attachments
scheduled_for_sending Boolean

PatternAttribute

PatternAttribute

Attributes

Name Type Nullable Description
id Integer
permalink String

PatternAttribute (list)

Attributes

Name Type Nullable Description
description String Long attribute description
id Integer
name String Attribute name
sort_order Integer Sort order within the containing attribute group. If not present, sorting alphabetically is recommended.

Tool

Tool

Attributes

Name Type Nullable Description
created_at Date
id Integer
make String Yes
model String Yes
name String Yes
notes String Yes
updated_at Date

Tool (full)

Attributes

Name Type Nullable Description
created_at Date
id Integer
make String Yes
model String Yes
name String Yes
notes String Yes
updated_at Date

Store

Store

Attributes

Name Type Nullable Description
business Business The business (Pro Account) associated with the store
id Integer Store ID
name String Store name
pattern_source
paypal_account String (deprecated) For stores that use the legacy non-Marketplaces PayPal connection, the associated account
permalink String Store permalink
products_count Integer Number of products in the store

Store (list)

Attributes

Name Type Nullable Description
business Business The business (Pro Account) associated with the store
id Integer Store ID
name String Store name
pattern_source
paypal_account String (deprecated) For stores that use the legacy non-Marketplaces PayPal connection, the associated account
permalink String Store permalink
products_count Integer Number of products in the store

CartItem

CartItem (javascript)

Attributes

Name Type Nullable Description
cart_id Integer cart identifier
currency String 3 character currency code
id Integer cart item identifier
product Array, Product (javascript) list of products

CartItem (full)

Attributes

Name Type Nullable Description
cart_id Integer cart identifier
currency String 3 character currency code
id Integer cart item identifier
product Array, Product (full) list of products

FiberCategory

FiberCategory

Attributes

Name Type Nullable Description
id Integer
name String Short category name
parent
permalink String

FiberCategory (list)

Attributes

Name Type Nullable Description
children Array, FiberCategory (list) Child categories (subcategories)
id Integer
name String Short category name
permalink String
short_name String Abbreviated category name

Bundle

Bundle (list)

Attributes

Name Type Nullable Description
bundle_cover Photo Yes A cover photo uploaded by the user - this takes precedence over first_photo
bundled_items_count Integer Yes
first_photo Photo Yes A photo of a bundled item within the bundle
id Integer
name String
notes String Yes
user User (small) User that is the Bundle owner

Bundle (full)

Attributes

Name Type Nullable Description
bundle_cover Photo Yes A cover photo uploaded by the user - this takes precedence over first_photo
bundled_items Array, BundledItem (list) Yes list of the items in the bundle
bundled_items_count Integer Yes
created_at Date
favorites_count Integer Yes
first_photo Photo Yes A photo of a bundled item within the bundle
id Integer
name String
notes String Yes
permalink String
updated_at Date
user User (small) User that is the Bundle owner

Bundle (export)

Attributes

Name Type Nullable Description
bundle_cover Photo Yes A cover photo uploaded by the user - this takes precedence over first_photo
bundled_items Array, BundledItem (list) Yes list of the items in the bundle
bundled_items_count Integer Yes
created_at Date
favorites_count Integer Yes
first_photo Photo Yes A photo of a bundled item within the bundle
id Integer
name String
notes String Yes
permalink String
updated_at Date

Bundle (POST)

Attributes

Name Type Nullable Description
name String
notes String Yes
owner_id Integer Yes The ID of the bundle owner - only needed for PatternAuthor or Group owner_types
owner_id Integer Yes The ID of the bundle owner - only needed for PatternAuthor or Group owner_types
owner_type String Yes Who owns the bundle. Either designer or group for designer or group bundles. Leave blank for personal bundles.
owner_type String Yes Who owns the bundle. Either designer or group for designer or group bundles. Leave blank for personal bundles.

ColorFamily

ColorFamily

Attributes

Name Type Nullable Description
color String Yes HTML color code
id Integer
name String
permalink String
spectrum_order Integer sort order, (mostly) based on the spectrum

DraftComponentYarn

DraftComponentYarn

Attributes

Name Type Nullable Description
created_at Date
draft_pattern_id Integer
id Integer
updated_at Date

DraftComponentYarn (full)

Attributes

Name Type Nullable Description
created_at Date
draft_pattern_id Integer
held_together_group Integer
id Integer
updated_at Date
yarn Yarn (list)
yarn_weight YarnWeight (list)

DraftComponentYarn (POST)

Attributes

Name Type Nullable Description
yarn_weight_id Integer

Comment

Comment

Attributes

Name Type Nullable Description
comment_html String Comment body (HTML formatted)
created_at Date Creation time
highlighted_project Project Yes If the commenter has a project that is related to their comment, it is provided here. Note that you have to request this information as part of the comments API call.
id Integer Comment ID
user User (small) The user who posted the comment

Comment (history)

Attributes

Name Type Nullable Description
comment_html String Comment body (HTML formatted)
commentable
created_at Date Creation time
id Integer Comment ID
user_id Integer The ID of the user who posted the comment

Comment (full)

Attributes

Name Type Nullable Description
comment_html String Comment body (HTML formatted)
created_at Date Creation time
highlighted_project Project Yes If the commenter has a project that is related to their comment, it is provided here. Note that you have to request this information as part of the comments API call.
id Integer Comment ID
replies Array, Comment Replies to the comment. Only the owner of the item that has been commented on can reply, nesting is limited to 1 level (replies cannot have replies)
user User (small) The user who posted the comment

Comment (export)

Attributes

Name Type Nullable Description
comment_html String Comment body (HTML formatted)
created_at Date Creation time
id Integer Comment ID

Volume

Volume (full)

Attributes

Name Type Nullable Description
asking_price_cents
asking_price_currency String Yes
author_name String Yes
cover_image_size
cover_image_url
created_at Date Creation date
first_photo
for_sale
for_trade
has_downloads
id Integer
notes String Yes Notes related to this item
notes_html
pattern_id Integer Yes The pattern that this volume is related to
pattern_source_id Integer Yes The pattern source that this volume is related to
patterns_count Integer Yes
small_image_url
square_image_url
title String Yes
unapplied_updates Array, ProductNotification Yes List of unapplied updates for this volume, if any
updated_at Date Last update date
volume_attachments Array, VolumeAttachment Yes Documents (PDF files) that are attached to this volume
volume_status_id Integer Yes One of: 1 (no special status), 2 (for sale), 3 (for trade), 4 (for sale or trade)

Volume (list)

Attributes

Name Type Nullable Description
author_name String Yes
cover_image_size
cover_image_url
created_at Date Creation date
first_photo
has_downloads
id Integer
pattern_id Integer Yes The pattern that this volume is related to
pattern_source_id Integer Yes The pattern source that this volume is related to
patterns_count Integer Yes
small_image_url
square_image_url
title String Yes
updated_at Date Last update date

Volume (export)

Attributes

Name Type Nullable Description
author_name String Yes
cover_image_size
cover_image_url
created_at Date Creation date
first_photo
has_downloads
id Integer
pattern_id Integer Yes The pattern that this volume is related to
pattern_source_id Integer Yes The pattern source that this volume is related to
patterns_count Integer Yes
small_image_url
square_image_url
title String Yes
updated_at Date Last update date

Volume (POST)

Attributes

Name Type Nullable Description
asking_price String Yes Asking price, if the item is for sale
asking_price_currency String Yes
location String Yes Location where the item is stored, only visible to the owner
notes String Yes Notes related to this item
pattern_id Integer Yes The pattern that this volume is related to
pattern_source_id Integer Yes The pattern source that this volume is related to
volume_status_id Integer Yes One of: 1 (no special status), 2 (for sale), 3 (for trade), 4 (for sale or trade)

Shop

Shop

Attributes

Name Type Nullable Description
address
city
closed
country
distance
facebook_page
free_wifi
id
latitude
location
longitude
name
parking
permalink
phone
pos_online
ravelry_retailer
seating
shop_email
state
twitter_id
url
wheelchair_access
zip

Shop (tiny)

Attributes

Name Type Nullable Description
id
name
permalink

Shop (small)

Attributes

Name Type Nullable Description
address
city
closed
country
distance
facebook_page
free_wifi
id
latitude
location
longitude
name
parking
permalink
phone
pos_online
ravelry_retailer
seating
shop_email
state
twitter_id
url
wheelchair_access
zip

Shop (medium)

Attributes

Name Type Nullable Description
address
city
closed
country
distance
facebook_page
free_wifi
id
latitude
location
longitude
name
notes_html
parking
permalink
phone
pos_online
ravelry_retailer
seating
shop_email
state
twitter_id
url
wheelchair_access
yarn_brands
zip

Cart

Cart (javascript)

Attributes

Name Type Nullable Description
cart_items Array, CartItem (javascript) Yes list of items in the cart
currency String 3 letter code for the currency of the cart
id Integer cart identifier
store_id Integer store identifier

Cart (full)

Attributes

Name Type Nullable Description
cart_items Array, CartItem (full) Yes list of items in the cart
currency String 3 letter code for the currency of the cart
id Integer cart identifier
store_id Integer store identifier

DownloadLink

Attributes

Name Type Nullable Description
activated_at
expires_at
url

Stash

Stash

Attributes

Name Type Nullable Description
color_family_name
colorway_name
comments_count Integer
created_at Date
dye_lot String Yes
favorites_count Integer
first_photo Photo
handspun Boolean
has_photo Boolean Yes
id Integer
location String Yes Description of where the stashed yarn is stored
long_yarn_weight_name String Longer description of the yarn's weight. personal_yarn_weight is used if there is no associated yarn
name String Yes User-added yarn name, typically present when there is no associated yarn
permalink String
personal_yarn_weight YarnWeight Yes User-added yarn weight, typically present when there is no associated yarn
stash_status
tag_names Array, String List of tags associated with this stash entry
updated_at Date
user User (small) User that is the Stash owner
yarn Yarn (stash_list)
yarn_weight_name String Name of the yarn's weight. personal_yarn_weight is used if there is no associated yarn

Stash (small)

Attributes

Name Type Nullable Description
color_family_name
colorway_name
comments_count Integer
created_at Date
dye_lot String Yes
favorites_count Integer
first_photo Photo
handspun Boolean
has_photo Boolean Yes
id Integer
location String Yes Description of where the stashed yarn is stored
name String Yes User-added yarn name, typically present when there is no associated yarn
permalink String
stash_status
tag_names Array, String List of tags associated with this stash entry
updated_at Date
yarn Yarn (stash_list)

Stash (list)

Attributes

Name Type Nullable Description
color_family_name
colorway_name
comments_count Integer
created_at Date
dye_lot String Yes
favorites_count Integer
first_photo Photo
handspun Boolean
has_photo Boolean Yes
id Integer
location String Yes Description of where the stashed yarn is stored
long_yarn_weight_name String Longer description of the yarn's weight. personal_yarn_weight is used if there is no associated yarn
name String Yes User-added yarn name, typically present when there is no associated yarn
permalink String
personal_yarn_weight YarnWeight Yes User-added yarn weight, typically present when there is no associated yarn
primary_pack (stash)
stash_status
tag_names Array, String List of tags associated with this stash entry
updated_at Date
user User (small) User that is the Stash owner
yarn Yarn (stash_list)
yarn_weight_name String Name of the yarn's weight. personal_yarn_weight is used if there is no associated yarn

Stash (list_with_notes)

Attributes

Name Type Nullable Description
color_family_name
colorway_name
comments_count Integer
created_at Date
dye_lot String Yes
favorites_count Integer
first_photo Photo
handspun Boolean
has_photo Boolean Yes
id Integer
location String Yes Description of where the stashed yarn is stored
long_yarn_weight_name String Longer description of the yarn's weight. personal_yarn_weight is used if there is no associated yarn
name String Yes User-added yarn name, typically present when there is no associated yarn
notes_html
notes
permalink String
personal_yarn_weight YarnWeight Yes User-added yarn weight, typically present when there is no associated yarn
primary_pack (stash)
stash_status
tag_names Array, String List of tags associated with this stash entry
updated_at Date
user User (small) User that is the Stash owner
yarn Yarn (stash_list)
yarn_weight_name String Name of the yarn's weight. personal_yarn_weight is used if there is no associated yarn

Stash (full)

Attributes

Name Type Nullable Description
color_family_name
colorway_name
comments_count Integer
created_at Date
dye_lot String Yes
favorites_count Integer
handspun Boolean
has_photo Boolean Yes
id Integer
location String Yes Description of where the stashed yarn is stored
long_yarn_weight_name String Longer description of the yarn's weight. personal_yarn_weight is used if there is no associated yarn
name String Yes User-added yarn name, typically present when there is no associated yarn
name String Yes User-added yarn name, typically present when there is no associated yarn
notes_html
notes
packs (stash)
permalink String
personal_yarn_weight YarnWeight Yes User-added yarn weight, typically present when there is no associated yarn
photos (full)
stash_status
tag_names Array, String List of tags associated with this stash entry
updated_at Date
user User (small) User that is the Stash owner
user_id
yarn Yarn (full)
yarn_weight_name String Name of the yarn's weight. personal_yarn_weight is used if there is no associated yarn

Stash (full_for_owner)

Attributes

Name Type Nullable Description
color_family_name
colorway_name
comments_count Integer
created_at Date
dye_lot String Yes
favorites_count Integer
handspun Boolean
has_photo Boolean Yes
id Integer
location String Yes Description of where the stashed yarn is stored
long_yarn_weight_name String Longer description of the yarn's weight. personal_yarn_weight is used if there is no associated yarn
name String Yes User-added yarn name, typically present when there is no associated yarn
name String Yes User-added yarn name, typically present when there is no associated yarn
notes_html
notes
packs (stash_for_owner)
permalink String
personal_yarn_weight YarnWeight Yes User-added yarn weight, typically present when there is no associated yarn
photos (full)
stash_status
tag_names Array, String List of tags associated with this stash entry
updated_at Date
user User (small) User that is the Stash owner
user_id
yarn Yarn (full)
yarn_weight_name String Name of the yarn's weight. personal_yarn_weight is used if there is no associated yarn

Stash (export)

Attributes

Name Type Nullable Description
color_family_name
colorway_name
comments_count Integer
created_at Date
dye_lot String Yes
favorites_count Integer
handspun Boolean
has_photo Boolean Yes
id Integer
location String Yes Description of where the stashed yarn is stored
long_yarn_weight_name String Longer description of the yarn's weight. personal_yarn_weight is used if there is no associated yarn
name String Yes User-added yarn name, typically present when there is no associated yarn
name String Yes User-added yarn name, typically present when there is no associated yarn
notes_html
notes
packs (stash)
permalink String
personal_yarn_weight YarnWeight Yes User-added yarn weight, typically present when there is no associated yarn
photos (full)
stash_status
tag_names Array, String List of tags associated with this stash entry
updated_at Date
user_id
yarn Yarn (full)
yarn_weight_name String Name of the yarn's weight. personal_yarn_weight is used if there is no associated yarn

Stash (POST)

Attributes

Name Type Nullable Description
dye_lot String Yes
handspun Boolean
location String Yes Description of where the stashed yarn is stored
notes
pack Pack (POST) Yes The pack record contains detailed information about an allocation of yarn
stash_status_id Integer 1 = active, 2 = used up, 3 = will trade/sell, 4 = gone/sold, 5 = in progress (only available on handspun)
tag_list String Yes List of tags, space delimited
yarn_id Integer Yes Yarn to link the stash entry to

Forum

Forum (small)

Attributes

Name Type Nullable Description
id Integer
name String
permalink String
sort_order Integer
topics_count Integer

Forum (list)

Attributes

Name Type Nullable Description
id Integer
name String
permalink String
sort_order Integer
topics_count Integer

Project

Project

Attributes

Name Type Nullable Description
comments_count Integer
completed Date Yes
completed_day_set Boolean If set to false, the "completed" date day is unknown. It represents a month and year only
craft_id Integer Yes
craft_name
created_at Date
ends_per_inch Decimal Yes
favorites_count Integer
first_photo Photo Yes
gauge_divisor Integer Yes
gauge Decimal Yes
gauge_pattern String Yes
gauge_repeats Integer Yes
id Integer
links Object Links to the project on Ravelry
made_for String Yes
made_for_user_id Integer Yes
name String
pattern_id Integer Yes A project might have a pattern name and no pattern ID (if it is not linked to a Ravelry database pattern)
pattern_name String Yes
permalink String
personal_attributes Hash Yes Hash containing information related to this project's status in the current user's notebook (favorited, bookmark_id, ...)
photos_count Integer
picks_per_inch Decimal Yes
progress Integer Yes
project_status_changed
project_status_id Integer Yes
rating Integer Yes
row_gauge Decimal Yes
size String Yes
started Date Yes
started_day_set Boolean If set to false, the "started" date day is unknown. It represents a month and year only
status_name String Yes
tag_names Array Yes Array of tags (tags cannot contain commas)
updated_at Date
user User (small) User that is the Project owner
user_id

Project (notes)

Attributes

Name Type Nullable Description
comments_count Integer
completed Date Yes
completed_day_set Boolean If set to false, the "completed" date day is unknown. It represents a month and year only
craft_id Integer Yes
craft_name
created_at Date
ends_per_inch Decimal Yes
favorites_count Integer
first_photo Photo Yes
gauge_divisor Integer Yes
gauge Decimal Yes
gauge_pattern String Yes
gauge_repeats Integer Yes
id Integer
links Object Links to the project on Ravelry
made_for String Yes
made_for_user_id Integer Yes
name String
notes_html String Yes Public project notes
notes String Yes Public project notes, raw markdown before rendering as HTML and sanitizing
pattern_id Integer Yes A project might have a pattern name and no pattern ID (if it is not linked to a Ravelry database pattern)
pattern_name String Yes
permalink String
personal_attributes Hash Yes Hash containing information related to this project's status in the current user's notebook (favorited, bookmark_id, ...)
photos_count Integer
picks_per_inch Decimal Yes
progress Integer Yes
project_status_changed
project_status_id Integer Yes
rating Integer Yes
row_gauge Decimal Yes
size String Yes
started Date Yes
started_day_set Boolean If set to false, the "started" date day is unknown. It represents a month and year only
status_name String Yes
tag_names Array Yes Array of tags (tags cannot contain commas)
updated_at Date
user User (small) User that is the Project owner
user_id

Project (list_with_packs)

Attributes

Name Type Nullable Description
comments_count Integer
completed Date Yes
completed_day_set Boolean If set to false, the "completed" date day is unknown. It represents a month and year only
craft_id Integer Yes
craft_name
created_at Date
ends_per_inch Decimal Yes
favorites_count Integer
first_photo Photo Yes
gauge_divisor Integer Yes
gauge Decimal Yes
gauge_pattern String Yes
gauge_repeats Integer Yes
id Integer
links Object Links to the project on Ravelry
made_for String Yes
made_for_user_id Integer Yes
name String
notes_html String Yes Public project notes
notes String Yes Public project notes, raw markdown before rendering as HTML and sanitizing
packs Pack (full) Yes Array of pack records containing detailed information about an allocation of yarn. Only allowed on project creation. For updating or deleting use the pack API methods.
pattern_id Integer Yes A project might have a pattern name and no pattern ID (if it is not linked to a Ravelry database pattern)
pattern_name String Yes
permalink String
personal_attributes Hash Yes Hash containing information related to this project's status in the current user's notebook (favorited, bookmark_id, ...)
photos_count Integer
picks_per_inch Decimal Yes
progress Integer Yes
project_status_changed
project_status_id Integer Yes
rating Integer Yes
row_gauge Decimal Yes
size String Yes
started Date Yes
started_day_set Boolean If set to false, the "started" date day is unknown. It represents a month and year only
status_name String Yes
tag_names Array Yes Array of tags (tags cannot contain commas)
updated_at Date
user User (small) User that is the Project owner
user_id

Project (small)

Attributes

Name Type Nullable Description
comments_count Integer
completed Date Yes
completed_day_set Boolean If set to false, the "completed" date day is unknown. It represents a month and year only
craft_id Integer Yes
craft_name
created_at Date
ends_per_inch Decimal Yes
favorites_count Integer
first_photo Photo Yes
gauge_divisor Integer Yes
gauge Decimal Yes
gauge_pattern String Yes
gauge_repeats Integer Yes
id Integer
links Object Links to the project on Ravelry
made_for String Yes
made_for_user_id Integer Yes
name String
pattern_id Integer Yes A project might have a pattern name and no pattern ID (if it is not linked to a Ravelry database pattern)
pattern_name String Yes
permalink String
photos_count Integer
picks_per_inch Decimal Yes
progress Integer Yes
project_status_changed
project_status_id Integer Yes
rating Integer Yes
row_gauge Decimal Yes
size String Yes
started Date Yes
started_day_set Boolean If set to false, the "started" date day is unknown. It represents a month and year only
status_name String Yes
tag_names Array Yes Array of tags (tags cannot contain commas)
updated_at Date
user_id

Project (full)

Attributes

Name Type Nullable Description
comments_count Integer
completed Date Yes
completed_day_set Boolean If set to false, the "completed" date day is unknown. It represents a month and year only
craft_id Integer Yes
craft_name
created_at Date
ends_per_inch Decimal Yes
favorites_count Integer
gauge_divisor Integer Yes
gauge Decimal Yes
gauge_pattern String Yes
gauge_repeats Integer Yes
id Integer
links Object Links to the project on Ravelry
made_for String Yes
made_for_user_id Integer Yes
name String
needle_sizes
notes_html String Yes Public project notes
notes String Yes Public project notes, raw markdown before rendering as HTML and sanitizing
packs Pack (full) Yes Array of pack records containing detailed information about an allocation of yarn. Only allowed on project creation. For updating or deleting use the pack API methods.
pattern_id Integer Yes A project might have a pattern name and no pattern ID (if it is not linked to a Ravelry database pattern)
pattern_name String Yes
permalink String
personal_attributes Hash Yes Hash containing information related to this project's status in the current user's notebook (favorited, bookmark_id, ...)
photos (full)
photos_count Integer
picks_per_inch Decimal Yes
progress Integer Yes
project_status_changed
project_status_id Integer Yes
rating Integer Yes
row_gauge Decimal Yes
size String Yes
started Date Yes
started_day_set Boolean If set to false, the "started" date day is unknown. It represents a month and year only
status_name String Yes
tag_names Array Yes Array of tags (tags cannot contain commas)
tools (full)
updated_at Date
user User (small) User that is the Project owner
user_id

Project (full_for_owner)

Attributes

Name Type Nullable Description
comments_count Integer
completed Date Yes
completed_day_set Boolean If set to false, the "completed" date day is unknown. It represents a month and year only
craft_id Integer Yes
craft_name
created_at Date
ends_per_inch Decimal Yes
favorites_count Integer
gauge_divisor Integer Yes
gauge Decimal Yes
gauge_pattern String Yes
gauge_repeats Integer Yes
id Integer
links Object Links to the project on Ravelry
made_for String Yes
made_for_user_id Integer Yes
name String
needle_sizes
notes_html String Yes Public project notes
notes String Yes Public project notes, raw markdown before rendering as HTML and sanitizing
packs Pack (full_for_owner) Yes Array of pack records containing detailed information about an allocation of yarn. Only allowed on project creation. For updating or deleting use the pack API methods.
pattern_id Integer Yes A project might have a pattern name and no pattern ID (if it is not linked to a Ravelry database pattern)
pattern_name String Yes
permalink String
personal_attributes Hash Yes Hash containing information related to this project's status in the current user's notebook (favorited, bookmark_id, ...)
photos (full)
photos_count Integer
picks_per_inch Decimal Yes
private_notes_html String Yes Private project notes, only viewable by the project owner
private_notes String Yes Private project notes, raw markdown before rendering as HTML and sanitizing
progress Integer Yes
project_status_changed
project_status_id Integer Yes
rating Integer Yes
row_gauge Decimal Yes
size String Yes
started Date Yes
started_day_set Boolean If set to false, the "started" date day is unknown. It represents a month and year only
status_name String Yes
tag_names Array Yes Array of tags (tags cannot contain commas)
tools (full)
updated_at Date
user User (small) User that is the Project owner
user_id

Project (export)

Attributes

Name Type Nullable Description
comments_count Integer
completed Date Yes
completed_day_set Boolean If set to false, the "completed" date day is unknown. It represents a month and year only
craft_id Integer Yes
craft_name
created_at Date
ends_per_inch Decimal Yes
favorites_count Integer
gauge_divisor Integer Yes
gauge Decimal Yes
gauge_pattern String Yes
gauge_repeats Integer Yes
id Integer
links Object Links to the project on Ravelry
made_for String Yes
made_for_user_id Integer Yes
name String
needle_sizes
notes_html String Yes Public project notes
notes String Yes Public project notes, raw markdown before rendering as HTML and sanitizing
packs Pack (full) Yes Array of pack records containing detailed information about an allocation of yarn. Only allowed on project creation. For updating or deleting use the pack API methods.
pattern_id Integer Yes A project might have a pattern name and no pattern ID (if it is not linked to a Ravelry database pattern)
pattern_name String Yes
permalink String
personal_attributes Hash Yes Hash containing information related to this project's status in the current user's notebook (favorited, bookmark_id, ...)
photos (full)
photos_count Integer
picks_per_inch Decimal Yes
private_notes_html String Yes Private project notes, only viewable by the project owner
private_notes String Yes Private project notes, raw markdown before rendering as HTML and sanitizing
progress Integer Yes
project_status_changed
project_status_id Integer Yes
rating Integer Yes
row_gauge Decimal Yes
size String Yes
started Date Yes
started_day_set Boolean If set to false, the "started" date day is unknown. It represents a month and year only
status_name String Yes
tag_names Array Yes Array of tags (tags cannot contain commas)
tools (full)
updated_at Date
user_id

Project (POST)

Attributes

Name Type Nullable Description
completed Date Yes
completed Date Yes
craft_id Integer Yes
craft_id Integer Yes
ends_per_inch
gauge
gauge_divisor
gauge_pattern
gauge_repeats
made_for String Yes
made_for_user_id Integer Yes
made_for_user_id Integer Yes
name String
needle_sizes Array, Object (POST) Yes List of needle size IDs. We will replace any existing needles with the contents of this array.
notes String Yes Public project notes
packs Pack (POST) Yes Array of pack records containing detailed information about an allocation of yarn. Only allowed on project creation. For updating or deleting use the pack API methods.
pattern_id Integer Yes A project might have a pattern name and no pattern ID (if it is not linked to a Ravelry database pattern)
personal_pattern_name String Yes
picks_per_inch
private_notes String Yes Private project notes, only viewable by the project owner
progress Integer Yes
project_status_id Integer Yes
project_status_id Integer Yes
rating Integer Yes
row_gauge
size String Yes
started Date Yes
started Date Yes
tag_names Array (POST) Yes Array of tags (tags cannot contain commas)

ForumStatisticSummary

ForumStatisticSummary

Attributes

Name Type Nullable Description
forum_id Integer
new_topics_30day Integer
new_topics_7day Integer
new_topics_avg Integer
pageviews_30day Integer
pageviews_7day Integer
pageviews_avg Integer
posts_30day Integer
posts_7day Integer
posts_avg Integer
unique_pageviews_30day Integer
unique_pageviews_7day Integer
unique_pageviews_avg Integer

PatternTagging

PatternTagging

Attributes

Name Type Nullable Description
id Integer
pattern_attribute_id Integer
pattern_id Integer

PatternTagging (list)

Attributes

Name Type Nullable Description
id Integer
pattern_attribute PatternAttribute (list) Pattern attribute
pattern_attribute_id Integer
pattern_id Integer

PatternTagging (POST)

Attributes

Name Type Nullable Description
id Integer
pattern_attribute_id Integer

AttributeGroup

AttributeGroup (list)

Attributes

Name Type Nullable Description
children Array, AttributeGroup (list) Child attribute groups (subgroups)
id Integer
name String Attribute group name
pattern_attributes Array, PatternAttribute (list) Attributes contained in this group
permalink String

YarnAttributeGroup

YarnAttributeGroup

Attributes

Name Type Nullable Description
id Integer
name String Attribute group name
permalink String

YarnAttributeGroup (full)

Attributes

Name Type Nullable Description
id Integer
name String Attribute group name
permalink String

YarnAttributeGroup (list)

Attributes

Name Type Nullable Description
children Array, YarnAttributeGroup (list) Child yarn attribute groups (subgroups)
id Integer
name String Attribute group name
permalink String
yarn_attributes

YarnCountry

YarnCountry

Attributes

Name Type Nullable Description
advertising_shops Integer Number of shops that are advertising this yarn
country_id Integer Country identifier
id Integer
shops_with_patrons Integer Number of unique shops where this yarn was purchased (recently or at any time in the past)
shops_with_patrons_30days Integer Number of unique shops where this yarn was purchased during the last 30 days
shops_with_patrons_60days Integer Number of unique shops where this yarn was purchased during the last 60 days
shops_with_patrons_90days Integer Number of unique shops where this yarn was purchased during the last 90 days
yarn_id Integer Yarn identifier

YarnCountry (full)

Attributes

Name Type Nullable Description
advertising_shops Integer Number of shops that are advertising this yarn
country_id Integer Country identifier
country_name
id Integer
shops_with_patrons Integer Number of unique shops where this yarn was purchased (recently or at any time in the past)
shops_with_patrons_30days Integer Number of unique shops where this yarn was purchased during the last 30 days
shops_with_patrons_60days Integer Number of unique shops where this yarn was purchased during the last 60 days
shops_with_patrons_90days Integer Number of unique shops where this yarn was purchased during the last 90 days
yarn_id Integer Yarn identifier

FiberType

FiberType (full)

Attributes

Name Type Nullable Description
animal_fiber Boolean
id Integer
name String
synthetic Boolean
vegetable_fiber Boolean

Pack

Pack (stash)

Attributes

Name Type Nullable Description
color_attributes
color_family_id String Yes Color family. See /color_families.json
colorway
dye_lot String Yes Dye lot, name or number from ball band or free-form text
grams_per_skein
id
meters_per_skein
ounces_per_skein
personal_name String Yes Personal name, use if not linking to a database yarn
prefer_metric_length
prefer_metric_weight
primary_pack_id
project_id Integer Yes Project the pack is affiliated with
quantity_description
shop_id Integer Yes Shop that the yarn was purchased from. See /shops/
shop_name
skeins String Yes # of skeins of this yarn.
stash_id Integer Yes Stash the pack is affiliated with
thread_size
total_grams
total_meters
total_ounces
total_yards
yards_per_skein
yarn_id Integer Yes Yarn that this pack (allocation of yarn) is linked to. NOTE: you only need to supply the yarn if you are associating a pack with a project and that pack is not also associated with a stash entry. On Ravelry, this would be akin to adding a yarn to your project and linking it to a yarn (and not a stash entry)

Pack (stash_for_owner)

Attributes

Name Type Nullable Description
color_attributes
color_family_id String Yes Color family. See /color_families.json
colorway
dye_lot String Yes Dye lot, name or number from ball band or free-form text
grams_per_skein
id
meters_per_skein
ounces_per_skein
personal_name String Yes Personal name, use if not linking to a database yarn
prefer_metric_length
prefer_metric_weight
primary_pack_id
project_id Integer Yes Project the pack is affiliated with
quantity_description
shop_id Integer Yes Shop that the yarn was purchased from. See /shops/
shop_name
skeins String Yes # of skeins of this yarn.
stash_id Integer Yes Stash the pack is affiliated with
thread_size
total_grams
total_meters
total_ounces
total_paid_currency
total_paid
total_yards
yards_per_skein
yarn_id Integer Yes Yarn that this pack (allocation of yarn) is linked to. NOTE: you only need to supply the yarn if you are associating a pack with a project and that pack is not also associated with a stash entry. On Ravelry, this would be akin to adding a yarn to your project and linking it to a yarn (and not a stash entry)

Pack (full)

Attributes

Name Type Nullable Description
color_family_id String Yes Color family. See /color_families.json
colorway
dye_lot String Yes Dye lot, name or number from ball band or free-form text
grams_per_skein
id
meters_per_skein
ounces_per_skein
personal_name String Yes Personal name, use if not linking to a database yarn
prefer_metric_length
prefer_metric_weight
primary_pack_id
project_id Integer Yes Project the pack is affiliated with
quantity_description
shop_id Integer Yes Shop that the yarn was purchased from. See /shops/
shop_name
skeins String Yes # of skeins of this yarn.
stash_id Integer Yes Stash the pack is affiliated with
thread_size
total_grams
total_meters
total_ounces
total_yards
yards_per_skein
yarn
yarn_id Integer Yes Yarn that this pack (allocation of yarn) is linked to. NOTE: you only need to supply the yarn if you are associating a pack with a project and that pack is not also associated with a stash entry. On Ravelry, this would be akin to adding a yarn to your project and linking it to a yarn (and not a stash entry)
yarn_name
yarn_weight

Pack (full_for_owner)

Attributes

Name Type Nullable Description
color_family_id String Yes Color family. See /color_families.json
colorway
dye_lot String Yes Dye lot, name or number from ball band or free-form text
grams_per_skein
id
meters_per_skein
ounces_per_skein
personal_name String Yes Personal name, use if not linking to a database yarn
prefer_metric_length
prefer_metric_weight
primary_pack_id
project_id Integer Yes Project the pack is affiliated with
quantity_description
shop_id Integer Yes Shop that the yarn was purchased from. See /shops/
shop_name
skeins String Yes # of skeins of this yarn.
stash_id Integer Yes Stash the pack is affiliated with
thread_size
total_grams
total_meters
total_ounces
total_paid_currency
total_paid
total_yards
yards_per_skein
yarn
yarn_id Integer Yes Yarn that this pack (allocation of yarn) is linked to. NOTE: you only need to supply the yarn if you are associating a pack with a project and that pack is not also associated with a stash entry. On Ravelry, this would be akin to adding a yarn to your project and linking it to a yarn (and not a stash entry)
yarn_name
yarn_weight

Pack (public)

Attributes

Name Type Nullable Description
id
yarn_id Integer Yes Yarn that this pack (allocation of yarn) is linked to. NOTE: you only need to supply the yarn if you are associating a pack with a project and that pack is not also associated with a stash entry. On Ravelry, this would be akin to adding a yarn to your project and linking it to a yarn (and not a stash entry)

Pack (POST)

Attributes

Name Type Nullable Description
color_family_id String Yes Color family. See /color_families.json
colorway String Yes Colorway. Number or name from ball band or free form description.
dye_lot String Yes Dye lot, name or number from ball band or free-form text
length_units String Yes One of 'yards', 'meters'
personal_gauge_divisor String Yes Personal gauge info, use if not linking to a database yarn
personal_max_gauge Integer Yes Personal gauge info, use if not linking to a database yarn
personal_min_gauge Integer Yes Personal gauge info, use if not linking to a database yarn
personal_name String Yes Personal name, use if not linking to a database yarn
personal_shop_name String Yes Personal purchase information, use if not linking to a shop
personal_thread_size
personal_yarn_weight_id Integer Yes Personal yarn weight, use if not linking to a yarn. See /yarn_weights.json
project_id Integer Yes Project the pack is affiliated with
purchased_city String Yes Personal purchase information, use if not linking to a shop
purchased_country_id Integer Yes Personal purchase information, use if not linking to a shop
purchased_date Date Yes Date that the yarn was purchased. YYYY-MM-DD format.
purchased_state_id Integer Yes Personal purchase information, use if not linking to a shop
purchased_url String Yes Personal purchase information, use if not linking to a shop
shop_id Integer Yes Shop that the yarn was purchased from. See /shops/
skein_length String Yes length of a skein of this yarn.
skein_weight String Yes weight of a skein of this yarn.
skeins String Yes # of skeins of this yarn.
stash_id Integer Yes Stash the pack is affiliated with
total_length String Yes length of this allocation of yarn.
total_paid String Yes Amount paid for this quantity of yarn
total_paid_currency String Yes 3 character currency code
total_weight String Yes weight of this allocation of yarn.
weight_units String Yes One of 'grams', 'ounces'
yarn_id Integer Yes Yarn that this pack (allocation of yarn) is linked to. NOTE: you only need to supply the yarn if you are associating a pack with a project and that pack is not also associated with a stash entry. On Ravelry, this would be akin to adding a yarn to your project and linking it to a yarn (and not a stash entry)

Topic

Topic (list)

Attributes

Name Type Nullable Description
archived Boolean
created_at Date
forum_id Integer
forum_images_count Integer
forum_posts_count Integer
id Integer
ignored
last_read Integer Post number for the last post that the current user has read
latest_reply Integer Post number for the latest reply
locked Boolean Topic is marked as "locked" and does not accept replies
no_chat
replied_at Date
sticky Boolean Topic is marked as "no chat" and does not accept replies to individual posts
title String
watched

Topic (browse)

Attributes

Name Type Nullable Description
archived Boolean
created_at Date
forum Forum (small)
forum_id Integer
forum_images_count Integer
forum_posts_count Integer
id Integer
ignored
last_read Integer Post number for the last post that the current user has read
latest_reply Integer Post number for the latest reply
locked Boolean Topic is marked as "locked" and does not accept replies
no_chat
replied_at Date
sticky Boolean Topic is marked as "no chat" and does not accept replies to individual posts
title String
watched

Topic (full)

Attributes

Name Type Nullable Description
archived Boolean
can_edit_as_moderator
created_at Date
created_by_user
forum Forum (small)
forum_id Integer
forum_images_count Integer
forum_posts_count Integer
id Integer
ignored
last_read
latest_reply Integer Post number for the latest reply
locked Boolean Topic is marked as "locked" and does not accept replies
no_chat
replied_at Date
sticky Boolean Topic is marked as "no chat" and does not accept replies to individual posts
summary_html String Yes Summary/notes section rendered into HTML
summary
title String
watched

Group

Group (list)

Attributes

Name Type Nullable Description
badge_url String Yes URL to badge image
banner_url String Yes URL to banner image
created_at Date
forum Forum (list) The forum associated with this group
forum_id Integer
id Integer
mature Boolean True if the owners have marked the group as "mature"
name String Name of this group
permalink String
short_description String Short description of this group

UnifiedStash

UnifiedStash (list)

Attributes

Name Type Nullable Description
fiber_stash FiberStash Yes If this is a fiber stash result, the fiber stash model will be present under this key
stash Stash Yes If this is a stash result, the stash model will be present under this key

ProductNotification

ProductNotification

Attributes

Name Type Nullable Description
created_at Date Creation date
id Integer Product notification identifier
message String Yes Message included in the notification, in markdown format
message_html String Yes Message included in the notification, in HTML format
product_id Integer ID of the product this notification is related to
version String Yes File version info for this notification

Saleable

Saleable

Attributes

Name Type Nullable Description
created_at Date When the record was created
id Integer Saleable ID. A Saleable record connects a Product to the Pattern or PatternSource page where that Product is listed for sale.
product_id Integer Product ID
saleable_id Integer ID for the associated record (a Pattern, PatternSource, or DraftPattern)
saleable_type String Type of the associated record ("Pattern", "PatternSource", or "DraftPattern")
updated_at Date When the record was last updated

Product

Product (javascript)

Attributes

Name Type Nullable Description
active Boolean Product is active and available for purchase. Can be set to false at any time, can be set to true if the product is set up (including attachments) and the store is open for business.
id Integer Product identifier
pretty_price String price with currency symbol
price String Yes Price, for non-free products
sku String Product SKU. Typically you will keep the default unless matching SKUs in external systems is needed/desirable
store_id String Store identifier
title String Product title/description

Product (list)

Attributes

Name Type Nullable Description
active Boolean Product is active and available for purchase. Can be set to false at any time, can be set to true if the product is set up (including attachments) and the store is open for business.
attachment_bytes Integer total size of files attached to the product
currency String Yes 3 character currency code, for non-free products
designer_photos_count Integer the number of photos associated with the product that were created by the designer (ie. contributed user photos are not included)
free Boolean Yes Free, true for free products
has_notes
id Integer Product identifier
languages Array, String list of language codes that the included files cover (ISO 639-1 language codes) If the list is not known, an empty array is returned.
mature_content Boolean true if the linked item's subject matter, title, or image is classified as "mature content"
photos_count Integer the number of photos associated with the product
pretty_price String price with currency symbol
price String Yes Price, for non-free products
product_type
saleables
sku String Product SKU. Typically you will keep the default unless matching SKUs in external systems is needed/desirable
square_thumbnail_url
store_id String Store identifier
title String Product title/description

Product (full)

Attributes

Name Type Nullable Description
active Boolean Product is active and available for purchase. Can be set to false at any time, can be set to true if the product is set up (including attachments) and the store is open for business.
attachments
currency String Yes 3 character currency code, for non-free products
free Boolean Yes Free, true for free products
id Integer Product identifier
pattern_sources Array, PatternSource The pattern sources that are currently associated with this product
patterns Array, Pattern The patterns that are currently associated with this product
pretty_price String price with currency symbol
pretty_wholesale_price String Yes wholesale price with currency symbol
price String Yes Price, for non-free products
product_type
saleables
sku String Product SKU. Typically you will keep the default unless matching SKUs in external systems is needed/desirable
store_id String Store identifier
title String Product title/description
wholesale_price String Yes price paid by yarn stores participating in In Store Sales

Product (delivery)

Attributes

Name Type Nullable Description
active Boolean Product is active and available for purchase. Can be set to false at any time, can be set to true if the product is set up (including attachments) and the store is open for business.
id Integer Product identifier
pattern_sources Array, PatternSource The pattern sources that are currently associated with this product
patterns Array, Pattern The patterns that are currently associated with this product
product_type
sku String Product SKU. Typically you will keep the default unless matching SKUs in external systems is needed/desirable
store_id String Store identifier
title String Product title/description

Product (POST)

Attributes

Name Type Nullable Description
active Boolean Product is active and available for purchase. Can be set to false at any time, can be set to true if the product is set up (including attachments) and the store is open for business.
currency String Yes 3 character currency code, for non-free products
free Boolean Yes Free, true for free products
price String Yes Price, for non-free products
reporting_tag String Yes Optional tag that appears in data exports. Not visible to customers.
sku String Product SKU. Typically you will keep the default unless matching SKUs in external systems is needed/desirable
title String Product title/description
wholesale Boolean Yes For stores that are enrolled in In Store Sales program, set this to true to make a product available to Local Yarn Stores via In Store Sales

Ad

Ad (shop)

Attributes

Name Type Nullable Description
logo_url
target_url String

ForumPreference

ForumPreference (list)

Attributes

Name Type Nullable Description
forum Forum
position Integer User's sort order for this forum

Attributes

Name Type Nullable Description
created_at
draft_pattern_id
id
updated_at
url

NeedleRecord

NeedleRecord (small)

Attributes

Name Type Nullable Description
comment
id
needle_type_id

NeedleRecord (full)

Attributes

Name Type Nullable Description
comment
id
needle_type
needle_type_id

QueuedStash

QueuedStash (full)

Attributes

Name Type Nullable Description
created_at
id
queued_project_id
stash
stash_id
updated_at

FiberStash

FiberStash

Attributes

Name Type Nullable Description
colorway_name
comments_count Integer
created_at Date
favorites_count Integer
fiber_company_name String Yes
first_photo Photo
has_photo Boolean Yes
id Integer
location String Yes
long_name String Yes name including the fiber company name
name String Yes The name that the user has given this stash entry
permalink String
stash_status StashStatus Yes
updated_at Date
user User (small)
user_id Integer

FiberStash (list)

Attributes

Name Type Nullable Description
colorway_name
comments_count Integer
created_at Date
favorites_count Integer
fiber_company_name String Yes
first_photo Photo
has_photo Boolean Yes
id Integer
location String Yes
long_name String Yes name including the fiber company name
name String Yes The name that the user has given this stash entry
permalink String
stash_status StashStatus Yes
updated_at Date
user User (small)
user_id Integer

FiberStash (full)

Attributes

Name Type Nullable Description
colorway_name
comments_count Integer
created_at Date
favorites_count Integer
fiber_company_name String Yes
fiber_packs FiberPack (stash)
has_photo Boolean Yes
id Integer
location String Yes
long_name String Yes name including the fiber company name
name String Yes The name that the user has given this stash entry
notes_html String Notes for this entry, rendered as HTML
permalink String
photos Photo (full)
stash_status StashStatus Yes
updated_at Date
user User (small)
user_id Integer

FiberStash (export)

Attributes

Name Type Nullable Description
colorway_name
comments_count Integer
created_at Date
favorites_count Integer
fiber_company_name String Yes
fiber_packs FiberPack (stash)
has_photo Boolean Yes
id Integer
location String Yes
long_name String Yes name including the fiber company name
name String Yes The name that the user has given this stash entry
notes_html String Notes for this entry, rendered as HTML
permalink String
photos Photo (full)
stash_status StashStatus Yes
updated_at Date
user_id Integer

FiberStash (POST)

Attributes

Name Type Nullable Description
fiber_company_name String Yes
fiber_pack
location String Yes
name String Yes The name that the user has given this stash entry
notes
stash_status_id

YarnCompany

YarnCompany

Attributes

Name Type Nullable Description
id
logo_url
name
permalink
url
yarns_count

YarnCompany (full)

Attributes

Name Type Nullable Description
id
logo_url
name
permalink
url
yarns_count

YarnCompany (list)

Attributes

Name Type Nullable Description
id
logo_url
name
permalink
url
yarns_count

YarnCompany (public)

Attributes

Name Type Nullable Description
id
name
permalink
url

YarnCompany (shop)

Attributes

Name Type Nullable Description
advertised
id
most_recent_purchase
name
permalink
purchases

InvoiceLineItem

InvoiceLineItem (sale)

Attributes

Name Type Nullable Description
amount Decimal Amount of the invoice attributed to this item. WIll be negative for promotions.
id Integer Invoice line item ID
product_id Integer Yes Promotion ID, if this item is a promotion
promotion_id Integer Yes Product ID, if this item is a product
promotional_discount_applied Decimal Yes If a promotion was applied to this product, `promotional_discount_applied` will contain the share of the discount that relates to this line item
title

YarnFiber

YarnFiber (full)

Attributes

Name Type Nullable Description
fiber_category FiberCategory (full)
fiber_type FiberType (full)
id Integer
percentage Integer

YarnFiber (public)

Attributes

Name Type Nullable Description
fiber_category_id
fiber_type_id
id Integer
percentage Integer

PatternCategory

PatternCategory

Attributes

Name Type Nullable Description
id Integer
name String Short category name
parent
permalink String

PatternCategory (list)

Attributes

Name Type Nullable Description
children Array, PatternCategory (list) Child categories (subcategories)
id Integer
long_name String Descriptive category name
name String Short category name
permalink String

Photo

Photo

Attributes

Name Type Nullable Description
aspect_ratio Float Aspect ratio of the photo
caption String Yes Photo caption
caption_html String Yes Photo caption, with image tags instead of emoji
copyright_holder
id
medium2_url String Medium2 image, 640 pixels on the longest side. For larger images suitable for zooming, see /photos/{id}/sizes.json
medium_url String Medium image, 500 pixels on the longest side. You can get exact dimensions by using /photos/dimensions.json.
small2_url String Small2 image, 320 pixels on the longest side. You can get exact dimensions by using /photos/dimensions.json.
small_url String Small image, 240 pixels on the longest side. You can get exact dimensions by using /photos/dimensions.json.
sort_order
square_url String A tiny, square thumbnail, 75 x 75px
thumbnail_url String Thumbnail, 100 pixels on the longest side
user_id Integer User ID of the photo's owner/uploader
x_offset Integer Yes X offset for centered photo. See POST /photos/{id}.json for more information.
y_offset Integer Yes Y offset for centered photo. See POST /photos/{id}.json for more information.

Photo (small)

Attributes

Name Type Nullable Description
aspect_ratio Float Aspect ratio of the photo
caption String Yes Photo caption
caption_html String Yes Photo caption, with image tags instead of emoji
copyright_holder
id
medium2_url String Medium2 image, 640 pixels on the longest side. For larger images suitable for zooming, see /photos/{id}/sizes.json
medium_url String Medium image, 500 pixels on the longest side. You can get exact dimensions by using /photos/dimensions.json.
small2_url String Small2 image, 320 pixels on the longest side. You can get exact dimensions by using /photos/dimensions.json.
small_url String Small image, 240 pixels on the longest side. You can get exact dimensions by using /photos/dimensions.json.
sort_order
square_url String A tiny, square thumbnail, 75 x 75px
thumbnail_url String Thumbnail, 100 pixels on the longest side
user_id Integer User ID of the photo's owner/uploader
x_offset Integer Yes X offset for centered photo. See POST /photos/{id}.json for more information.
y_offset Integer Yes Y offset for centered photo. See POST /photos/{id}.json for more information.

Photo (full)

Attributes

Name Type Nullable Description
aspect_ratio Float Aspect ratio of the photo
caption String Yes Photo caption
caption_html String Yes Photo caption, with image tags instead of emoji
copyright_holder
flickr_url
id
medium2_url String Medium2 image, 640 pixels on the longest side. For larger images suitable for zooming, see /photos/{id}/sizes.json
medium_url String Medium image, 500 pixels on the longest side. You can get exact dimensions by using /photos/dimensions.json.
shelved_url String Yes A book cover image, 150 pixels wide
small2_url String Small2 image, 320 pixels on the longest side. You can get exact dimensions by using /photos/dimensions.json.
small_url String Small image, 240 pixels on the longest side. You can get exact dimensions by using /photos/dimensions.json.
sort_order
square_url String A tiny, square thumbnail, 75 x 75px
thumbnail_url String Thumbnail, 100 pixels on the longest side
user_id Integer User ID of the photo's owner/uploader
x_offset Integer Yes X offset for centered photo. See POST /photos/{id}.json for more information.
y_offset Integer Yes Y offset for centered photo. See POST /photos/{id}.json for more information.

BundledItem

BundledItem (small)

Attributes

Name Type Nullable Description
bundle_id Integer Bundle ID
id Integer bundled item identifier
item_id Integer item identifier. May only be set during creation.
item_type String the type of item - clipping, pattern, designer, project, stash, yarn_company, yarn, shop, forum_post, fiber_stash, bundle, or pattern_source
user User (small) User that is the item owner

BundledItem (list)

Attributes

Name Type Nullable Description
bookmark Bookmark (list) Yes Bookmark attached to bundled item
bundle_id Integer Bundle ID
created_at Date
id Integer bundled item identifier
item_id Integer item identifier. May only be set during creation.
item_type String the type of item - clipping, pattern, designer, project, stash, yarn_company, yarn, shop, forum_post, fiber_stash, bundle, or pattern_source
notes String Yes
updated_at Date

BundledItem (full)

Attributes

Name Type Nullable Description
bookmark Bookmark (full) Yes Bookmark attached to bundled item
bundle_id Integer Bundle ID
created_at Date
id Integer bundled item identifier
item_id Integer item identifier. May only be set during creation.
item_type String the type of item - clipping, pattern, designer, project, stash, yarn_company, yarn, shop, forum_post, fiber_stash, bundle, or pattern_source
notes String Yes
updated_at Date
user User (small) User that is the item owner

BundledItem (POST)

Attributes

Name Type Nullable Description
bookmark_id Integer Bookmark ID, if this item is associated with a favorite
bundle_id Integer Bundle ID
item_id Integer item identifier. May only be set during creation.
item_id Integer item identifier. May only be set during creation.
item_type String the type of item - clipping, pattern, designer, project, stash, yarn_company, yarn, shop, forum_post, fiber_stash, bundle, or pattern_source
item_type String the type of item - clipping, pattern, designer, project, stash, yarn_company, yarn, shop, forum_post, fiber_stash, bundle, or pattern_source
notes String Yes
user_id Integer User ID of the item owner.

ProjectStatus

ProjectStatus (list)

Attributes

Name Type Nullable Description
id
name
permalink

ComponentYarn

ComponentYarn

Attributes

Name Type Nullable Description
combined_yarn_weight_id Integer Combined (effective) weight of all yarns held together
id Integer
pattern_id Integer Pattern ID
yarn_id Integer Yarn ID

ComponentYarn (list)

Attributes

Name Type Nullable Description
combined_yarn_weight_id Integer Combined (effective) weight of all yarns held together
created_at Date
held_together_group Integer Yes
id Integer
pattern_id Integer Pattern ID
updated_at Date
yarn_id Integer Yarn ID

ComponentYarn (POST)

Attributes

Name Type Nullable Description
combined_yarn_weight_id Integer Combined (effective) weight of all yarns held together
id Integer
yarn_id Integer Yarn ID

PatternSourceType

PatternSourceType

Attributes

Name Type Nullable Description
can_add_to_library
id Integer
long_name
name String Name of the source type
requires_url Boolean true if sources of this type require a URL

PatternSourceType (list)

Attributes

Name Type Nullable Description
can_add_to_library
id Integer
long_name
name String Name of the source type
requires_url Boolean true if sources of this type require a URL

ForumSet

ForumSet (list)

Attributes

Name Type Nullable Description
default
id
name
permalink
selected_forums
sort_order

InStoreSale

InStoreSale (receipt)

Attributes

Name Type Nullable Description
deliveries Array, Delivery (receipt) Details about digital products that are being delivered to the customer
id Integer In Store Sale ID
invoice Invoice (receipt) Invoice details
seller_store_name String Name of the seller store that is being purchased from

Page

Page (full)

Attributes

Name Type Nullable Description
body
name

Pattern

Pattern

Attributes

Name Type Nullable Description
designer PatternAuthor
first_photo Photo Yes
id Integer
name String Pattern name
pattern_author PatternAuthor
pattern_sources
permalink String

Attributes

Name Type Nullable Description
id Integer
name String Pattern name
permalink String

Pattern (list)

Attributes

Name Type Nullable Description
designer PatternAuthor
first_photo Photo Yes
free Boolean Free pattern (available free from Ravelry or free from some other source)
id Integer
name String Pattern name
pattern_author PatternAuthor
pattern_sources
permalink String
personal_attributes Hash Hash containing information related to this pattern's status in the current user's notebook (queued, favorited, bookmark_id)

Pattern (source_list)

Attributes

Name Type Nullable Description
first_photo Photo Yes
id Integer
name String Pattern name
pattern_author PatternAuthor
permalink String

Pattern (full)

Attributes

Name Type Nullable Description
comments_count Integer
craft Craft (list)
created_at Date Date that this pattern record was created
currency String Currency for price. Will be a PayPal-supported currency: https://www.paypal.com/cgi-bin/webscr?cmd=p/sell/mc/mc_wa-outside
currency_symbol
difficulty_average Float
difficulty_count Integer
download_location DownloadLocation Where to download or purchase the pattern - contains a URL, free flag, and type ("ravelry" or "external")
downloadable Boolean
favorites_count Integer
free Boolean Free pattern (available free from Ravelry or free from some other source)
free Boolean Free pattern (available free from Ravelry or free from some other source)
gauge String Gauge
gauge_description String
gauge_divisor Integer Gauge divisor (ie. stitches per [divisor]"), in inches. Accepted options: 1, 2, 4 corresponding to 1" (2.5cm), 2" (5cm), 4" (10cm).
gauge_pattern String Pattern for gauge (free form text)
gauge_repeats String
generally_available Date Our best estimate of the date when this pattern first became available to the public. Not displayed on the pattern page.
has_uk_terminology Boolean Crochet pattern includes UK terminology
has_us_terminology Boolean Crochet pattern includes US terminology
id Integer
languages
name String Pattern name
notes_html String Pattern notes rendered as HTML.
notes
packs Pack (full) Packs connect a pattern to a suggested yarn. Within a pack, only "yarn_id" is required.
pattern_attributes Array, PatternAttribute
pattern_author PatternAuthor
pattern_categories Array, PatternCategory
pattern_needle_sizes String
pattern_type
pdf_in_library Boolean Set to "true" if the user's library contains PDF files for this pattern.
pdf_url String
permalink String
personal_attributes Hash Hash containing information related to this pattern's status in the current user's notebook (queued, favorited, bookmark_id)
photos Array, Photo
price String Price. If the pattern is associated with a Ravelry download, the price is retrieved from the product and the price attribute is read-only.
printings Printing (list)
product_id Integer Product ID for the product that is currently listed on the pattern page as a "buy now" option, if any
projects_count Integer
published Date Date the pattern was published, displayed on the pattern page (also see "generally_available")
queued_projects_count Integer
rating_average Float
rating_count Integer
ravelry_download Boolean
row_gauge String Row gauge
sizes_available String
unlisted_product_ids Array, Integer Product IDs for products that are not currently listed on the pattern page as a "buy now" option. Only present if the current user has editing permissions.
updated_at Date Date that this pattern record was last updated
url String
volumes_in_library Array, Integer Yes If the user has pattern PDFs in their library, the Volume IDs will be included. See /volumes/{id}.json
yardage Integer
yardage_description String
yardage_max Integer Maximum yardage. To supply meterage instead, see meterage_max.
yarn_list_type
yarn_weight YarnWeight (list)
yarn_weight_description String

Pattern (public)

Attributes

Name Type Nullable Description
craft_id Integer craft ID (crochet = 1, knitting = 2)
created_at Date Date that this pattern record was created
currency String Currency for price. Will be a PayPal-supported currency: https://www.paypal.com/cgi-bin/webscr?cmd=p/sell/mc/mc_wa-outside
currency_symbol
downloadable Boolean
free Boolean Free pattern (available free from Ravelry or free from some other source)
free Boolean Free pattern (available free from Ravelry or free from some other source)
gauge String Gauge
gauge_description String
gauge_divisor Integer Gauge divisor (ie. stitches per [divisor]"), in inches. Accepted options: 1, 2, 4 corresponding to 1" (2.5cm), 2" (5cm), 4" (10cm).
gauge_pattern String Pattern for gauge (free form text)
gauge_repeats String
generally_available Date Our best estimate of the date when this pattern first became available to the public. Not displayed on the pattern page.
has_uk_terminology Boolean Crochet pattern includes UK terminology
has_us_terminology Boolean Crochet pattern includes US terminology
id Integer
name String Pattern name
notes_html String Pattern notes rendered as HTML.
notes
packs Pack (public) Packs connect a pattern to a suggested yarn. Within a pack, only "yarn_id" is required.
pattern_attribute_ids
pattern_author_id
pattern_category_ids
pattern_needle_sizes String
pdf_url String
permalink String
price String Price. If the pattern is associated with a Ravelry download, the price is retrieved from the product and the price attribute is read-only.
printings Printing (public)
published Date Date the pattern was published, displayed on the pattern page (also see "generally_available")
row_gauge String Row gauge
sizes_available String
updated_at Date Date that this pattern record was last updated
url String
yardage Integer
yardage_description String
yardage_max Integer Maximum yardage. To supply meterage instead, see meterage_max.
yarn_list_type
yarn_weight_description String
yarn_weight_id Integer Yarn weight ID. See yarn_weights.json

Pattern (oembed)

Attributes

Name Type Nullable Description
currency_code
name String Pattern name
price
title
url

Pattern (POST)

Attributes

Name Type Nullable Description
component_yarns ComponentYarn (POST) (Only for patterns with yarns held together) Yarns held together to create a single strand of yarn for the pattern. Each contains a yarn ID and the final (combined) yarn weight ID (see yarn_weights.json)
craft_id Integer craft ID (crochet = 1, knitting = 2)
currency String Currency for price. Will be a PayPal-supported currency: https://www.paypal.com/cgi-bin/webscr?cmd=p/sell/mc/mc_wa-outside
free Boolean Free pattern (available free from Ravelry or free from some other source)
gauge String Gauge
gauge_divisor Integer Gauge divisor (ie. stitches per [divisor]"), in inches. Accepted options: 1, 2, 4 corresponding to 1" (2.5cm), 2" (5cm), 4" (10cm).
gauge_divisor Integer Gauge divisor (ie. stitches per [divisor]"), in inches. Accepted options: 1, 2, 4 corresponding to 1" (2.5cm), 2" (5cm), 4" (10cm).
gauge_pattern String Pattern for gauge (free form text)
gauge_repeats String
has_uk_terminology Boolean Crochet pattern includes UK terminology
has_us_terminology Boolean Crochet pattern includes US terminology
meterage_max Integer Maximum meterage. To supply yardage instead, see yardage_max.
meterage_min Integer Minimum meterage. To supply yardage instead, see yardage_min.
name String Pattern name
notes String Raw notes. May be mixed Markdown and HTML. Generally only useful when presenting a pattern notes editor.
only_available_with_yarn_purchase
packs Pack (POST) Packs connect a pattern to a suggested yarn. Within a pack, only "yarn_id" is required.
pattern_classifications PatternClassification (POST)
pattern_languages PatternLanguage (POST)
pattern_needle_sizes PatternNeedleSize (POST)
pattern_taggings PatternTagging (POST)
price String Price. If the pattern is associated with a Ravelry download, the price is retrieved from the product and the price attribute is read-only.
printings Printing (POST)
row_gauge String Row gauge
sizes_available String Sizes available (free form text)
url String
yardage_max Integer Maximum yardage. To supply meterage instead, see meterage_max.
yardage_min Integer Minimum yardage. To supply meterage instead, see meterage_min.
yarn_held_together Boolean "true" if component yarns are all held together
yarn_list_type
yarn_weight_id Integer Yarn weight ID. See yarn_weights.json

ForumPost

ForumPost

Attributes

Name Type Nullable Description
created_at Date
deleted Boolean If deleted, this flag will be set to true and the post body will contain a deletion message
editable Boolean True if the current user can edit this post
id Integer
parent_post_id Integer Yes Post ID of the parent post (the post that was replied to)
parent_post_number Integer Yes Post number of the parent post (the post that was replied to)
post_number Integer
reply_count Integer The number of replies to this post
topic Topic (list) The topic (thread) containing the post
topic_id Integer
updated_at Date
user User (small) The user who authored the post

ForumPost (list)

Attributes

Name Type Nullable Description
body
body_html
created_at Date
deleted Boolean If deleted, this flag will be set to true and the post body will contain a deletion message
editable Boolean True if the current user can edit this post
id Integer
parent_post_id Integer Yes Post ID of the parent post (the post that was replied to)
parent_post_number Integer Yes Post number of the parent post (the post that was replied to)
parent_post_user (small)
post_number Integer
reply_count Integer The number of replies to this post
topic_id Integer
updated_at Date
user User (small) The user who authored the post

ForumPost (full)

Attributes

Name Type Nullable Description
body
body_html
created_at Date
deleted Boolean If deleted, this flag will be set to true and the post body will contain a deletion message
editable Boolean True if the current user can edit this post
id Integer
parent_post_id Integer Yes Post ID of the parent post (the post that was replied to)
parent_post_number Integer Yes Post number of the parent post (the post that was replied to)
parent_post_user (small)
post_number Integer
reply_count Integer The number of replies to this post
short_abstract
topic_id Integer
updated_at Date
user User (small) The user who authored the post

ForumPost (export)

Attributes

Name Type Nullable Description
body
body_html
created_at Date
deleted Boolean If deleted, this flag will be set to true and the post body will contain a deletion message
editable Boolean True if the current user can edit this post
id Integer
parent_post_id Integer Yes Post ID of the parent post (the post that was replied to)
parent_post_number Integer Yes Post number of the parent post (the post that was replied to)
post_number Integer
reply_count Integer The number of replies to this post
short_abstract
topic_id Integer
updated_at Date

PatternLanguage

PatternLanguage

Attributes

Name Type Nullable Description
created_at
id Integer
language_id Integer
pattern_id Integer
updated_at

PatternLanguage (list)

Attributes

Name Type Nullable Description
created_at
id Integer
language Language (list) Language
language_id Integer
pattern_id Integer
updated_at

PatternLanguage (POST)

Attributes

Name Type Nullable Description
id Integer
language_id Integer

ShopSchedule

ShopSchedule (shop)

Attributes

Name Type Nullable Description
closed
closing_time Date Closing time in local time. Note that a (useless) date is currently included but a timezone is not included.
day_name
day_of_week
opening_time Date Opening time in local time. Note that a (useless) date is currently included but a timezone is not included.

CombinedCart

CombinedCart (full)

Attributes

Name Type Nullable Description
cart_items Array, CartItem (full) Contents of the cart
created_at Date
created_by_user_id Integer API user who created the cart
id Integer
shop_customer ShopCustomer Customer associated with the cart
updated_at Date

CombinedCart (POST)

Attributes

Name Type Nullable Description
shop_customer ShopCustomer (POST) Customer associated with the cart

Printing

Printing (list)

Attributes

Name Type Nullable Description
created_at Date
id Integer
pattern_id Integer
pattern_not_available Boolean Yes "true" if this pattern is not currently available from the source
pattern_source PatternSource
pattern_source PatternSource (list)
primary_source Boolean Yes "true" if this is the primary source for the pattern

Printing (public)

Attributes

Name Type Nullable Description
created_at Date
id Integer
pattern_id Integer
pattern_source_id Integer
primary_source Boolean Yes "true" if this is the primary source for the pattern

Printing (POST)

Attributes

Name Type Nullable Description
id Integer
pattern_not_available Boolean Yes "true" if this pattern is not currently available from the source
pattern_source_id Integer
primary_source Boolean Yes "true" if this is the primary source for the pattern

ProductAttachment

ProductAttachment

Attributes

Name Type Nullable Description
document Array, Document Details about the attached file
id Integer Product attachment ID
language_id Integer Language ID
product_id Integer Product ID

ProductAttachment (full)

Attributes

Name Type Nullable Description
created_at Date Time when the record was created
deleted
document Array, Document Details about the attached file
id Integer Product attachment ID
language_id Integer Language ID
product_id Integer Product ID
sort_order Integer Sort order
updated_at Date Time when the record was last updated

ProductAttachment (receipt)

Attributes

Name Type Nullable Description
document Array, Document Details about the attached file
id Integer Product attachment ID
product_id Integer Product ID
product_title

ProductAttachment (POST)

Attributes

Name Type Nullable Description
language_id Integer Language ID
sort_order Integer Sort order

DraftPatternSource

DraftPatternSource (full)

Attributes

Name Type Nullable Description
created_at DateTime
draft_pattern_id Integer
id Integer
isbn String Yes
issue String Yes
name String Yes Draft pattern name
notes
online Boolean Yes
out_of_print Boolean Yes
pattern_source PatternSource (list) Yes
pattern_source_id Integer Yes
pattern_source_type_id Integer Yes
primary Boolean Yes
print Boolean Yes
published DateTime Yes
publisher_business_id Integer Yes The Pro account that the source belongs to
ravelry_ebook Boolean Yes
ravelry_store Boolean Yes
source_group_name String Yes
updated_at DateTime
url String Yes

DraftPatternSource (POST)

Attributes

Name Type Nullable Description
id Integer
issue String Yes
month_published DateTime (POST) Yes Publication month. Day is ignored. (ex: 2022-05-01)
name String Yes Draft pattern name
pattern_source_id Integer Yes
pattern_source_type_id Integer Yes
publisher_business_id Integer Yes The Pro account that the source belongs to
url String Yes

SavedSearch

SavedSearch (list)

Attributes

Name Type Nullable Description
created_at Date
id Integer Saved search ID
last_loaded Date The last time this search was run by the user
search_parameters
search_path
search_type String One of: groups, patterns, stash, people, yarns, designers, projects, discussions, patternsources, events, fiberstashes
subscribed Boolean true if the user is "subscribed" to this search
subscription_updated_at
title
updated_at Date

DraftPattern

DraftPattern

Attributes

Name Type Nullable Description
id Integer draft pattern ID
name String Draft pattern name
permalink String

DraftPattern (list)

Attributes

Name Type Nullable Description
created_at
created_by_user (small)
id Integer draft pattern ID
name String Draft pattern name
permalink String
updated_at

DraftPattern (full)

Attributes

Name Type Nullable Description
craft_id Integer
currency String 3 letter currency code
downloadable Boolean "true" if the pattern is available digitally for download (anywhere)
draft_component_yarns Array, DraftComponentYarn (full)
draft_errata_links Array, DraftErrataLink (full)
draft_needle_sizes Array, DraftNeedleSize (full)
draft_pattern_author_name String
draft_pattern_sources Array, DraftPatternSource (full)
draft_pattern_yarns Array, DraftPatternYarn (full)
draft_use_default_pattern_author Boolean
draft_yardage_units String 'M' for meters, 'Y' for yards
free Boolean
gauge String
gauge_divisor String
gauge_pattern String
gauge_repeats String
id Integer draft pattern ID
languages Array, Language (list)
name String Draft pattern name
notes
notes_html String Notes (rendered as HTML)
only_available_with_yarn_purchase Boolean "true" if the pattern is only available with the purchase of a yarn
pattern_attributes Array, PatternAttribute (list)
pattern_categories Array, PatternCategory (list)
permalink String
prerelease_pattern_code String Yes Tester code, for linking projects to a draft pattern, if any
price Decimal
published Date
published_pattern_id Integer Yes ID of the published pattern that was created from this draft, if it has been published
row_gauge Integer
sizes_available String Sizes available (free form text list of sizes)
url String Primary non-Ravelry URL for information about this pattern (if one exists)
yardage_max Integer
yardage_min Integer
yarn_held_together Boolean "true" if component yarns are all held together
yarn_list_type Integer 1 = all of the listed yarns are used in the pattern, 2 = only some of the listed yarns are used in the pattern (ie. the list contains suggested/alternative yarns)
yarn_weight_id Integer

DraftPattern (POST)

Attributes

Name Type Nullable Description
craft_id Integer
currency String 3 letter currency code
downloadable Boolean "true" if the pattern is available digitally for download (anywhere)
draft_business_id Integer
draft_component_yarns Array, DraftComponentYarn (POST)
draft_needle_sizes Array, DraftNeedleSize (POST)
draft_pattern_author_name String
draft_pattern_sources Array, DraftPatternSource (POST)
draft_pattern_yarns Array, DraftPatternYarn (POST)
draft_store_id Integer Yes Pattern store to associate with this pattern
draft_yardage_units String 'M' for meters, 'Y' for yards
free Boolean
gauge String
gauge_divisor String
gauge_pattern String
gauge_repeats String
name String Draft pattern name
notes String Notes (original/markdown format)
only_available_with_yarn_purchase Boolean "true" if the pattern is only available with the purchase of a yarn
pattern_classifications Array, PatternClassification (POST)
pattern_languages Array, PatternLanguage (POST)
pattern_taggings Array, PatternTagging (POST)
price Decimal (POST)
published Date
row_gauge Integer
sizes_available String Sizes available (free form text list of sizes)
url String Primary non-Ravelry URL for information about this pattern (if one exists)
yardage_max Integer
yardage_min Integer
yarn_held_together Boolean "true" if component yarns are all held together
yarn_list_type Integer 1 = all of the listed yarns are used in the pattern, 2 = only some of the listed yarns are used in the pattern (ie. the list contains suggested/alternative yarns)
yarn_weight_id Integer

Collection

Collection (medium)

Attributes

Name Type Nullable Description
id Integer
permalink String
tag_names Array, String
title String

Activity

Activity (list)

Attributes

Name Type Nullable Description
activity_type_id Integer Activity type ID. A textual description is provided in activity_type_key
activity_type_key String String key for this activity type. ("added_project_photo", "queued_pattern", etc)
created_at Date Date/time of activity
descriptive_title String Name/title of the target with a qualifier (example: "Smith faved Neo's Hat")
id Integer Activity identifier
photo Photo (small) The photo associated with the activity
target_id Integer The target object associated with the activity (the target of "added_project_photo" is a Project, the target of "queued_pattern" is a QueuedProject, etc)
target_id Integer The target object associated with the activity (the target of "added_project_photo" is a Project, the target of "queued_pattern" is a QueuedProject, etc)
target_uri String URI for retrieving the target information. (Example: /projects/janesmith/mittens.json)
title String Name/title of the target
user User (small) The user that performed the activity

NeedleType

NeedleType

Attributes

Name Type Nullable Description
description
id
length
metric_name
name
needle_size_id
type_name

NeedleType (full)

Attributes

Name Type Nullable Description
description
id
length
metric_name
name
needle_size_id
type_name

StashStatus

StashStatus

Attributes

Name Type Nullable Description
id
name

Message

Message (list)

Attributes

Name Type Nullable Description
id Integer
message_type_name String
parent_message_id Integer Yes ID of the parent message, if this message is a reply
read_message Boolean True if the message has been read
recipient User Message recipient
replied Boolean True the recipient replied to this message
replied_at Date Yes Date a reply was sent
sender User Message sender
sent_at Date
subject String Message subject

Message (full)

Attributes

Name Type Nullable Description
content_html
folder_name String
id Integer
message_type_name String
parent_message_id Integer Yes ID of the parent message, if this message is a reply
read_message Boolean True if the message has been read
recipient User Message recipient
replied Boolean True the recipient replied to this message
replied_at Date Yes Date a reply was sent
sender User Message sender
sent_at Date
subject String Message subject

Message (export)

Attributes

Name Type Nullable Description
content_html
folder_name String
id Integer
message_type_name String
parent_message_id Integer Yes ID of the parent message, if this message is a reply
read_message Boolean True if the message has been read
recipient User Message recipient
replied Boolean True the recipient replied to this message
replied_at Date Yes Date a reply was sent
sender User Message sender
sent_at Date
subject String Message subject

Message (POST)

Attributes

Name Type Nullable Description
content String Message body. Markdown and limited HTML is supported. (TODO: Rich Content documentation)
recipient_user_id Integer Yes User to deliver the message to. One of recipient_user_id or recipient_login is required.
recipient_username Integer Yes User to deliver the message to. One of recipient_user_id or recipient_username is required.
subject String Message subject

Friendship

Friendship (list)

Attributes

Name Type Nullable Description
created_at Date Creation date
friend_avatar Hash Hash containing a large_photo_url (240x240 image), photo_url (100x100 image) and tiny_photo_url (25x25 image)
friend_id
friend_user_id Integer User ID of the friend
friend_username User Friend user name
id Integer ID of this friendship record
tag_names Array, String List of user defined tag names

Friendship (full)

Attributes

Name Type Nullable Description
created_at Date Creation date
friend_avatar Hash Hash containing a large_photo_url (240x240 image), photo_url (100x100 image) and tiny_photo_url (25x25 image)
friend_user User Complete user record for the friend
friend_user_id Integer User ID of the friend
friend_username User Friend user name
id Integer ID of this friendship record
tag_names Array, String List of user defined tag names

VolumeAttachment

VolumeAttachment

Attributes

Name Type Nullable Description
bytes Integer Size of the attached file in bytes
content_type String Content type of the attached file. Currently only "application/pdf" is supported.
filename String Name of the attached file.
language_code String Yes Language of the document, if available. ISO 639 language code
notes String Yes Notes added by the file's uploader/seller. Generally blank or an explanation of file contents if a product includes more than one file.
product_attachment_id Integer Use the product attachment ID with /product_attachment/{id}/generate_download_link.json to get a direct link to this PDF.
ravelry_download_url String Ravelry URL that a user can view in a browser in order to download the file. Requires a normal Ravelry session / authentication (ie. username/password)
thumbnail_url String URL to a thumbnail of the file. Thumbnails are 150 pixels high. PDF thumbnails are typically 116 x 150.

UserSite

UserSite

Attributes

Name Type Nullable Description
id
social_site SocialSite Details about the external site
url String URL to profile page on an external site
username String Username on an external site

UserSite (full)

Attributes

Name Type Nullable Description
id
social_site SocialSite Details about the external site
url String URL to profile page on an external site
username String Username on an external site

FiberAttribute

FiberAttribute

Attributes

Name Type Nullable Description
fiber_attribute_group_id Integer
id Integer
name String Short category name
permalink String

FiberAttributeGroup

FiberAttributeGroup

Attributes

Name Type Nullable Description
id Integer
name String Short category name
parent_id Integer
permalink String

SocialSite

SocialSite

Attributes

Name Type Nullable Description
active Boolean True if the site is currently shown on Ravelry profile pages
favicon_url
id Integer
name String Name of the site

Yarn

Yarn

Attributes

Name Type Nullable Description
certified_organic Boolean
discontinued Boolean
first_photo Photo
gauge_divisor Integer
grams Integer weight of a skein/ball of the yarn in grams
id Integer
machine_washable Boolean
max_gauge Integer
min_gauge Integer
name String
organic
permalink String
rating_average Float
rating_count Integer
rating_total Integer
texture String (obsolete, this has been superseded by yarn attributes)
thread_size
wpi Integer wraps per inch
yardage Integer
yarn_company_name String
yarn_weight YarnWeight (list)

Yarn (list)

Attributes

Name Type Nullable Description
certified_organic Boolean
discontinued Boolean
first_photo Photo
gauge_divisor Integer
grams Integer weight of a skein/ball of the yarn in grams
id Integer
machine_washable Boolean
max_gauge Integer
min_gauge Integer
name String
organic
permalink String
personal_attributes Hash Hash containing information related to this yarn's status in the current user's notebook (favorited, bookmark_id, stash_ids)
rating_average Float
rating_count Integer
rating_total Integer
texture String (obsolete, this has been superseded by yarn attributes)
thread_size
wpi Integer wraps per inch
yardage Integer
yarn_company_name String
yarn_weight YarnWeight (list)

Yarn (stash_list)

Attributes

Name Type Nullable Description
certified_organic Boolean
discontinued Boolean
gauge_divisor Integer
grams Integer weight of a skein/ball of the yarn in grams
id Integer
machine_washable Boolean
max_gauge Integer
min_gauge Integer
name String
notes_html_deprecated
organic
permalink String
photos_deprecated
rating_average Float
rating_count Integer
rating_total Integer
texture String (obsolete, this has been superseded by yarn attributes)
thread_size
wpi Integer wraps per inch
yardage Integer
yarn_company YarnCompany (list)
yarn_company_name String
yarn_weight YarnWeight (list)

Yarn (full)

Attributes

Name Type Nullable Description
certified_organic Boolean
discontinued Boolean
gauge_divisor Integer
grams Integer weight of a skein/ball of the yarn in grams
id Integer
machine_washable Boolean
max_gauge Integer
max_hook_size
max_needle_size
min_gauge Integer
min_hook_size
min_needle_size
name String
notes_html String
organic
permalink String
personal_attributes Hash Hash containing information related to this yarn's status in the current user's notebook (favorited, bookmark_id, stash_ids)
photos Array, Photo (full)
rating_average Float
rating_count Integer
rating_total Integer
texture String (obsolete, this has been superseded by yarn attributes)
thread_size
wpi Integer wraps per inch
yardage Integer
yarn_attributes Array, YarnAttribute (full) Yarn attributes. Examples: "Superwash", "Gradient".
yarn_company YarnCompany (full)
yarn_fibers Array, YarnFiber (full)
yarn_provenance Array, YarnProvenance (full) Yarn provenance/origin records containing both a location and information about what was done at that location. Examples: "Dyed at (location)", "Milled in (location)".
yarn_weight YarnWeight (full)

Yarn (public)

Attributes

Name Type Nullable Description
certified_organic Boolean
discontinued Boolean
gauge_divisor Integer
grams Integer weight of a skein/ball of the yarn in grams
id Integer
machine_washable Boolean
max_gauge Integer
max_hook_size
max_needle_size
min_gauge Integer
min_hook_size
min_needle_size
name String
notes_html String
permalink String
texture String (obsolete, this has been superseded by yarn attributes)
thread_size
wpi Integer wraps per inch
yardage Integer
yarn_attribute_ids
yarn_attribute_ids
yarn_attributes Array, YarnAttribute (public) Yarn attributes. Examples: "Superwash", "Gradient".
yarn_company_id
yarn_fibers Array, YarnFiber (public)
yarn_weight_id

Yarn (oembed)

Attributes

Name Type Nullable Description
currency_code
name String
price
title
url

Bookmark

Bookmark (list)

Attributes

Name Type Nullable Description
comment String User defined comment
created_at Date
favorited Object The default output format for the favorited item is nested inside the result
id Integer Favorite ID
tag_list String Yes Space delimited list of tags (tags cannot contain commas)
type String The type of item that was favorited. One of: project, pattern, yarn, stash, forumpost, designer, yarnbrand, yarnshop

Bookmark (full)

Attributes

Name Type Nullable Description
bundles Bundle (list) The bundles that this favorite is a member of
comment String User defined comment
created_at Date
favorited Object The default output format for the favorited item is nested inside the result
id Integer Favorite ID
tag_list String Yes Space delimited list of tags (tags cannot contain commas)
type String The type of item that was favorited. One of: project, pattern, yarn, stash, forumpost, designer, yarnbrand, yarnshop

Bookmark (export)

Attributes

Name Type Nullable Description
bundles Bundle (list) The bundles that this favorite is a member of
comment String User defined comment
created_at Date
favorited Object The default output format for the favorited item is nested inside the result
id Integer Favorite ID
tag_list String Yes Space delimited list of tags (tags cannot contain commas)
type String The type of item that was favorited. One of: project, pattern, yarn, stash, forumpost, designer, yarnbrand, yarnshop

Bookmark (POST)

Attributes

Name Type Nullable Description
comment String User defined comment
favorited_id String The ID of the item that was favorited. May only be set during creation.
tag_list String Yes List of tags, space delimited
type String The type of item that was favorited. One of: project, pattern, yarn, stash, forumpost, designer, yarnbrand, yarnshop. May only be set during creation.

PatternClassification

PatternClassification

Attributes

Name Type Nullable Description
id Integer
pattern_category_id Integer
pattern_id Integer

PatternClassification (list)

Attributes

Name Type Nullable Description
id Integer
pattern_category Array, PatternCategory (list) Pattern category
pattern_category_id Integer
pattern_id Integer

PatternClassification (POST)

Attributes

Name Type Nullable Description
id Integer
pattern_category_id Integer

ShopCustomer

ShopCustomer

Attributes

Name Type Nullable Description
created_at Date Date and time that the customer record was created
customer_reference String Yes Usable by API clients - storage for reference information such as your customer ID, etc. Max length is 255 characters.
email_address String Yes Customer email
id
name String Yes Customer name
shop Shop (tiny) Yes The shop that the customer record is associated with
user User (small) Yes The customer's Ravelry account
user_id String Yes Customer's user ID

ShopCustomer (list)

Attributes

Name Type Nullable Description
created_at Date Date and time that the customer record was created
customer_reference String Yes Usable by API clients - storage for reference information such as your customer ID, etc. Max length is 255 characters.
email_address String Yes Customer email
id
name String Yes Customer name
shop Shop (tiny) Yes The shop that the customer record is associated with
user User (small) Yes The customer's Ravelry account
user_id String Yes Customer's user ID

ShopCustomer (POST)

Attributes

Name Type Nullable Description
email_address String Yes Customer email
name String Yes Customer name
user_id String Yes Customer's user ID

User

User

Attributes

Name Type Nullable Description
id
large_photo_url
photo_url
small_photo_url
tiny_photo_url
username

User (small)

Attributes

Name Type Nullable Description
id
large_photo_url
photo_url
profile_country_code
small_photo_url
tiny_photo_url
username

User (full)

Attributes

Name Type Nullable Description
about_me_html
about_me
fave_colors
fave_curse
first_name
id
large_photo_url
location
pattern_author PatternAuthor (for_user) The designer that is linked to this user
photo_url
profile_country_code
small_photo_url
tiny_photo_url
user_sites UserSite (full) Information about external social/etc sites that the user has added to their profile
username

User (export)

Attributes

Name Type Nullable Description
about_me_html
about_me
fave_colors
fave_curse
first_name
id
large_photo_url
location
pattern_author PatternAuthor (for_user) The designer that is linked to this user
photo_url
profile_country_code
small_photo_url
tiny_photo_url
user_sites UserSite (full) Information about external social/etc sites that the user has added to their profile
username

User (POST)

Attributes

Name Type Nullable Description
about_me String Yes "About me" text. Can contain markdown and/or HTML
fave_colors
fave_curse
first_name

PatternAuthor

PatternAuthor

Attributes

Name Type Nullable Description
crochet_pattern_count Integer Number of crochet patterns attributed to the designer
favorites_count Integer Number of times the designer has been favorited
id Integer
knitting_pattern_count Integer Number of knitting patterns attributed to the designer
name String Designer's full name or alias
patterns_count Integer Number of patterns attributed to the designer
permalink String
users Array, User (small) User accounts linked to this designer

PatternAuthor (full)

Attributes

Name Type Nullable Description
crochet_pattern_count Integer Number of crochet patterns attributed to the designer
favorites_count Integer Number of times the designer has been favorited
id Integer
knitting_pattern_count Integer Number of knitting patterns attributed to the designer
name String Designer's full name or alias
notes
notes_html
patterns_count Integer Number of patterns attributed to the designer
permalink String
users Array, User (full) User accounts linked to this designer

PatternAuthor (public)

Attributes

Name Type Nullable Description
id Integer
name String Designer's full name or alias
permalink String

PatternAuthor (for_user)

Attributes

Name Type Nullable Description
favorites_count Integer Number of times the designer has been favorited
id Integer
name String Designer's full name or alias
patterns_count Integer Number of patterns attributed to the designer
permalink String

Payment

Payment

Attributes

Name Type Nullable Description
gross Decimal Gross amount of the payment
id Integer Payment ID
txn_id Integer PayPal transaction ID
txn_type String PayPal txn_type (will typically be "express_checkout")

Payment (sale)

Attributes

Name Type Nullable Description
gross Decimal Gross amount of the payment
id Integer Payment ID
txn_id Integer PayPal transaction ID
txn_type String PayPal txn_type (will typically be "express_checkout")

Colorway

Colorway

Attributes

Name Type Nullable Description
code String Yes Code, for yarns with numeric/etc colorway codes
id Integer
name String
yarn_id Integer

Colorway (full)

Attributes

Name Type Nullable Description
code String Yes Code, for yarns with numeric/etc colorway codes
id Integer
name String
photo_url
projects_count Integer Number of projects using this colorway
stashes_count Integer Number of stashes using this colorway
usage_count
yarn_id Integer

Craft

Craft (list)

Attributes

Name Type Nullable Description
id Integer
name String
permalink String

Cross-Origin Resource Sharing (CORS)

CORS headers are set when making requests to api.ravelry.com

  • If your Authorization header includes a valid OAuth2 token, Access-Control-Allow-Origin is set to your list of redirect URIs
  • If you are using a different type of token or you are making a preflight OPTIONS request, Access-Control-Allow-Origin will match the Origin of your request
  • If something is wrong, Access-Control-Allow-Origin is set to this page. Make sure that you are requesting a JSON document from api.ravelry.com and that you are using a valid API key.

Use Etags to eliminate redundant result retrieval

  • In any API call, you will be sent an HTTP header called "Etag"

  • When you next make that API call again, send the etag value back to the API server in an "If-None-Match" HTTP Header. Etags are quoted so be sure to include the quotes in your header value.

    If-None-Match: "MyEtagValue"

  • If the result has changed, you'll get the new results.

    If the result has not changed, you'll get an HTTP 304 Not Modified and you can serve up a cached result instead of retrieving it over the network.

"Polling" for unread messages, etc

If you include the "extras=1" parameter in any API call, an object containing current message counts and other realtime-ish information will be included in the results.

Currently: extras: { unread_messages_count: 1, unread_forum_replies: 0 }

Activity Feeds

Pattern database additions and updates

A simple feed of recently added and updated patterns is available at https://api.ravelry.com/feeds/v1/patterns.

Usage tips:

  1. If you have an ETag from the last time you requested the URL, supply the value in the 'If-Modified-Since' header. You will receive a 304 Not Modified response if nothing has changed since the last request.
  2. If something has changed or if you did not supply an 'If-Modified-Since' header , you'll see the feed. Save the 'ETag' header for next time.
  3. If the date of the oldest record in the feed is still newer than the last time that you checked it, use the 'previous_page_url' to get the next page of older results.

Debugging requests

Your app's last 100 requests are visible in the debug log section of your App control panel in your Ravelry Pro account (http://www.ravelry.com/pro)

If you would like the JSON responses to be logged as well, include a debug=1 parameter in your requests. You may not enable response logging without the permission from the user.

automatically generated Last updated 2026-03-30